Overview:

Implement out-of-process dump generation for Windows platform.

Details:
- Created a lib, crash_generation.lib, that implements the out-of-process dump generation protocol.
- The lib code is under client/windows/crash_generation folder and is organized in the following way:
	- CrashGenerationServer class (crash_generation_server.h/.cc) implements the server side of
	  the protocol.
	- CrashGenerationClient class (crash_generation_client.h/.cc) implements the client side of
	  the protocol.
	- MinidumpGenerator class (minidump_generator.h/.cc) serves as an abstractino for generating
	  dump files using Windows APIs, coming up with new file names by creating GUIDs, etc.
	- ProtocolMessage class (ipc_protocol.h) represents the message format between the client and server
	  for pipe IPC.
	- Server allows one client at a time on the pipe in the current implementation.
	- ReadMe.txt explains the state machine the server uses to serve clients.
- ExceptionHandler is modified and a new constructor is added that allows specifying the pipe name. If the
  pipe name is NULL, the behavior is backward compatible - in-process dump generation is done as before. If
  the pipe name is specified, out-of-process dump generation registration is attempted. If that fails, the
  behavior is again backward compatible.
- If out-of-process registration succeeds, all write dump requests, direct or indirect, are directed to
  crash server process that served the registration request. NOTE that the explicit dump requests made by
  calling the static method of ExceptionHandler are not directed to theserver.
- client/windows/tests/crash_generation_app implements a simple Win32 GUI application to help test the
  out-of-process dump generation client and server. Typical use of the app is to start one instance, click
  Server --> Start and then start the other instance. The other instance will register with the first
  instance automatically at start-up. Then the second instance can be used to request various typoes of
  dump requests by using options under the Client menu.




git-svn-id: http://google-breakpad.googlecode.com/svn/trunk@244 4c0a9323-5329-0410-9bdc-e9ce6186880e

1 files changed, 255 insertions, 0 deletions

diff --git a/src/client/windows/crash_generation/crash_generation_server.h b/src/client/windows/crash_generation/crash_generation_server.h
new file mode 100644
index 00000000..864bacb1
--- /dev/null
+++ b/src/client/windows/crash_generation/crash_generation_server.h
@@ -0,0 +1,255 @@
+// Copyright (c) 2008, Google Inc.

+// All rights reserved.

+//

+// Redistribution and use in source and binary forms, with or without

+// modification, are permitted provided that the following conditions are

+// met:

+//

+//     * Redistributions of source code must retain the above copyright

+// notice, this list of conditions and the following disclaimer.

+//     * Redistributions in binary form must reproduce the above

+// copyright notice, this list of conditions and the following disclaimer

+// in the documentation and/or other materials provided with the

+// distribution.

+//     * Neither the name of Google Inc. nor the names of its

+// contributors may be used to endorse or promote products derived from

+// this software without specific prior written permission.

+//

+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+

+#ifndef CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__

+#define CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__

+

+#include <list>

+#include <string>

+#include "client/windows/common/ipc_protocol.h"

+#include "client/windows/crash_generation/client_info.h"

+#include "client/windows/crash_generation/minidump_generator.h"

+#include "processor/scoped_ptr.h"

+

+namespace google_breakpad {

+

+// Abstraction for server side implementation of out-of-process crash

+// generation protocol. It generates minidumps (Windows platform) for

+// client processes that request dump generation.

+class CrashGenerationServer {

+ public:

+  typedef void (*OnClientConnectedCallback)(void* context,

+                                            const ClientInfo* client_info);

+

+  typedef void (*OnClientDumpRequestCallback)(void* context,

+                                              const ClientInfo* client_info);

+

+  typedef void (*OnClientExitedCallback)(void* context,

+                                         const ClientInfo* client_info);

+

+  // Creates an instance with the given parameters.

+  //

+  // Parameter pipe_name: Name of the pipe

+  // Parameter connect_callback: Callback for a new client connection.

+  // Parameter connect_context: Context for client connection callback.

+  // Parameter crash_callback: Callback for a client crash dump request.

+  // Parameter crash_context: Context for client crash dump request callback.

+  // Parameter exit_callback: Callback for client process exit.

+  // Parameter exit_context: Context for client exit callback.

+  // Parameter generate_dumps: Whether to automatically generate dumps or not.

+  // Client code of this class might want to generate dumps explicitly in the

+  // crash dump request callback. In that case, false can be passed for this

+  // parameter.

+  // Parameter dump_path: Path for generating dumps; required only if true is

+  // passed for generateDumps parameter; NULL can be passed otherwise.

+  CrashGenerationServer(const wchar_t* pipe_name,

+                        OnClientConnectedCallback connect_callback,

+                        void* connect_context,

+                        OnClientDumpRequestCallback dump_callback,

+                        void* dump_context,

+                        OnClientExitedCallback exit_callback,

+                        void* exit_context,

+                        bool generate_dumps,

+                        const std::wstring* dump_path);

+

+  ~CrashGenerationServer();

+

+  // Performs initialization steps needed to start listening to clients.

+  //

+  // Returns true if initialization is successful; false otherwise.

+  bool Start();

+

+ private:

+  // Various states the client can be in during the handshake with

+  // the server.

+  enum IPCServerState {

+    // Server is in error state and it cannot serve any clients.

+    IPC_SERVER_STATE_ERROR,

+

+    // Server starts in this state.

+    IPC_SERVER_STATE_INITIAL,

+

+    // Server has issued an async connect to the pipe and it is waiting

+    // for the connection to be established.

+    IPC_SERVER_STATE_CONNECTING,

+

+    // Server is connected successfully.

+    IPC_SERVER_STATE_CONNECTED,

+

+    // Server has issued an async read from the pipe and it is waiting for

+    // the read to finish.

+    IPC_SERVER_STATE_READING,

+

+    // Server is done reading from the pipe.

+    IPC_SERVER_STATE_READ_DONE,

+

+    // Server has issued an async write to the pipe and it is waiting for

+    // the write to finish.

+    IPC_SERVER_STATE_WRITING,

+

+    // Server is done writing to the pipe.

+    IPC_SERVER_STATE_WRITE_DONE,

+

+    // Server has issued an async read from the pipe for an ack and it

+    // is waiting for the read to finish.

+    IPC_SERVER_STATE_READING_ACK,

+

+    // Server is done writing to the pipe and it is now ready to disconnect

+    // and reconnect.

+    IPC_SERVER_STATE_DISCONNECTING

+  };

+

+  //

+  // Helper methods to handle various server IPC states.

+  //

+  void HandleErrorState();

+  void HandleInitialState();

+  void HandleConnectingState();

+  void HandleConnectedState();

+  void HandleReadingState();

+  void HandleReadDoneState();

+  void HandleWritingState();

+  void HandleWriteDoneState();

+  void HandleReadingAckState();

+  void HandleDisconnectingState();

+

+  // Prepares reply for a client from the given parameters.

+  bool PrepareReply(const ClientInfo& client_info,

+                    ProtocolMessage* reply) const;

+

+  // Duplicates various handles in the ClientInfo object for the client

+  // process and stores them in the given ProtocolMessage instance. If

+  // creating any handle fails, ProtocolMessage will contain the handles

+  // already created successfully, which should be closed by the caller.

+  bool CreateClientHandles(const ClientInfo& client_info,

+                           ProtocolMessage* reply) const;

+

+  // Response to the given client. Return true if all steps of

+  // responding to the client succeed, false otherwise.

+  bool RespondToClient(ClientInfo* client_info);

+

+  // Handles a connection request from the client.

+  void HandleConnectionRequest();

+

+  // Handles a dump request from the client.

+  void HandleDumpRequest(const ClientInfo& client_info);

+

+  // Callback for pipe connected event.

+  static void CALLBACK OnPipeConnected(void* context, BOOLEAN timer_or_wait);

+

+  // Callback for a dump request.

+  static void CALLBACK OnDumpRequest(void* context, BOOLEAN timer_or_wait);

+

+  // Callback for client process exit event.

+  static void CALLBACK OnClientEnd(void* context, BOOLEAN timer_or_wait);

+

+  // Releases resources for a client.

+  static DWORD WINAPI CleanupClient(void* context);

+

+  // Cleans up for the given client.

+  void DoCleanup(ClientInfo* client_info);

+

+  // Adds the given client to the list of registered clients.

+  bool AddClient(ClientInfo* client_info);

+

+  // Generates dump for the given client.

+  bool GenerateDump(const ClientInfo& client);

+

+  // Sync object for thread-safe access to the shared list of clients.

+  CRITICAL_SECTION clients_sync_;

+

+  // List of clients.

+  std::list<ClientInfo*> clients_;

+

+  // Pipe name.

+  std::wstring pipe_name_;

+

+  // Handle to the pipe used for handshake with clients.

+  HANDLE pipe_;

+

+  // Pipe wait handle.

+  HANDLE pipe_wait_handle_;

+

+  // Handle to server-alive mutex.

+  HANDLE server_alive_handle_;

+

+  // Callback for a successful client connection.

+  OnClientConnectedCallback connect_callback_;

+

+  // Context for client connected callback.

+  void* connect_context_;

+

+  // Callback for a client dump request.

+  OnClientDumpRequestCallback dump_callback_;

+

+  // Context for client dump request callback.

+  void* dump_context_;

+

+  // Callback for client process exit.

+  OnClientExitedCallback exit_callback_;

+

+  // Context for client process exit callback.

+  void* exit_context_;

+

+  // Whether to generate dumps or not.

+  bool generate_dumps_;

+

+  // Instance of a mini dump generator.

+  scoped_ptr<MinidumpGenerator> dump_generator_;

+

+  // State of the server in performing the IPC with the client.

+  // Note that since we restrict the pipe to one instance, we

+  // only need to keep one state of the server. Otherwise, server

+  // would have one state per client it is talking to.

+  IPCServerState server_state_;

+

+  // Whether the server is shutting down.

+  volatile bool shutting_down_;

+

+  // Overlapped instance for async I/O on the pipe.

+  OVERLAPPED overlapped_;

+

+  // Message object used in IPC with the client.

+  ProtocolMessage msg_;

+

+  // Client Info for the client that's connecting to the server.

+  ClientInfo* client_info_;

+

+  // Count of clean-up work items that are currently running or are

+  // already queued to run.

+  volatile LONG cleanup_item_count_;

+

+  // Disable copy ctor and operator=.

+  CrashGenerationServer(const CrashGenerationServer& crash_server);

+  CrashGenerationServer& operator=(const CrashGenerationServer& crash_server);

+};

+

+}  // namespace google_breakpad

+

+#endif  // CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_SERVER_H__