[Mac] Replace the existing browser-child mach ipc with a long-lived listener ...

base/mach_ipc_mac.h

 // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_MACH_IPC_MAC_H_
 #define BASE_MACH_IPC_MAC_H_
 #pragma once
 
 #include <mach/mach.h>
 #include <mach/message.h>
 #include <servers/bootstrap.h>
 #include <sys/types.h>
 
 #include <CoreServices/CoreServices.h>
 
 #include "base/basictypes.h"
 
 //==============================================================================
 // DISCUSSION:
 //
 // The three main classes of interest are
 //
-//  MachMessage:    a wrapper for a mach message of the following form
+//  MachMessage:    a wrapper for a Mach message of the following form
 //   mach_msg_header_t
 //   mach_msg_body_t
 //   optional descriptors
 //   optional extra message data
 //
 //  MachReceiveMessage and MachSendMessage subclass MachMessage
 //    and are used instead of MachMessage which is an abstract base class
 //
 //  ReceivePort:
-//    Represents a mach port for which we have receive rights
+//    Represents a Mach port for which we have receive rights
 //
 //  MachPortSender:
-//    Represents a mach port for which we have send rights
+//    Represents a Mach port for which we have send rights
 //
 // Here's an example to receive a message on a server port:
 //
 //        // This creates our named server port
 //        ReceivePort receivePort("com.Google.MyService");
 //
 //        MachReceiveMessage message;
 //        kern_return_t result = receivePort.WaitForMessage(&message, 0);
 //
 //        if (result == KERN_SUCCESS && message.GetMessageID() == 57) {
@@ skipping 73 matching lines @@
     return *this;
   }
 
   // For convenience
   operator mach_port_t() const {
     return GetMachPort();
   }
 };
 
 //==============================================================================
-// MachMessage: a wrapper for a mach message
+// MachMessage: a wrapper for a Mach message
 //  (mach_msg_header_t, mach_msg_body_t, extra data)
 //
 //  This considerably simplifies the construction of a message for sending
 //  and the getting at relevant data and descriptors for the receiver.
 //
 //  This class can be initialized using external storage of an arbitrary size
 //  or it can manage storage internally.
 //  1. If storage is allocated internally, the combined size of the descriptors
 //  plus data must be less than 1024.  But as a benefit no memory allocation is
 //  necessary.
@@ skipping 17 matching lines @@
     return EndianU32_LtoN(GetDataPacket()->data_length);
   }
 
   // The message ID may be used as a code identifying the type of message
   void SetMessageID(int32_t message_id) {
     GetDataPacket()->id = EndianU32_NtoL(message_id);
   }
 
   int32_t GetMessageID() { return EndianU32_LtoN(GetDataPacket()->id); }
 
-  // Adds a descriptor (typically a mach port) to be translated
+  // Adds a descriptor (typically a Mach port) to be translated
   // returns true if successful, otherwise not enough space
   bool AddDescriptor(const MachMsgPortDescriptor &desc);
 
   int GetDescriptorCount() const {
     return storage_->body.msgh_descriptor_count;
   }
 
   MachMsgPortDescriptor *GetDescriptor(int n);
 
-  // Convenience method which gets the mach port described by the descriptor
+  // Convenience method which gets the Mach port described by the descriptor
   mach_port_t GetTranslatedPort(int n);
 
   // A simple message is one with no descriptors
   bool IsSimpleMessage() const { return GetDescriptorCount() == 0; }
 
   // Sets raw data for the message (returns false if not enough space)
   bool SetData(const void* data, int32_t data_length);
 
  protected:
   // Consider this an abstract base class - must create an actual instance
@@ skipping 16 matching lines @@
 
   MessageDataPacket* GetDataPacket();
 
   void SetDescriptorCount(int n);
   void SetDescriptor(int n, const MachMsgPortDescriptor &desc);
 
   // Returns total message size setting msgh_size in the header to this value
   int CalculateSize();
 
   // Returns total storage size that this object can grow to, this is inclusive
-  // of the mach header.
+  // of the Mach header.
   size_t MaxSize() const { return storage_length_bytes_; }
 
  protected:
   mach_msg_header_t *Head() { return &(storage_->head); }
 
  private:
   struct MachMessageData {
     mach_msg_header_t  head;
     mach_msg_body_t    body;
     // descriptors and data may be embedded here.
     u_int8_t           padding[1024];
   };
 
  // kEmptyMessageSize needs to have the definition of MachMessageData before
  // it.
  public:
    // The size of an empty message with no data.
   static const size_t kEmptyMessageSize = sizeof(mach_msg_header_t) +
                                           sizeof(mach_msg_body_t) +
                                           sizeof(MessageDataPacket);
 
  private:
   MachMessageData *storage_;
   size_t storage_length_bytes_;
   bool own_storage_;  // Is storage owned by this object?
 };
 
 //==============================================================================
 // MachReceiveMessage and MachSendMessage are useful to separate the idea
-// of a mach message being sent and being received, and adds increased type
+// of a Mach message being sent and being received, and adds increased type
 // safety:
 //  ReceivePort::WaitForMessage() only accepts a MachReceiveMessage
 //  MachPortSender::SendMessage() only accepts a MachSendMessage
 
 //==============================================================================
 class MachReceiveMessage : public MachMessage {
  public:
   MachReceiveMessage() : MachMessage() {}
   MachReceiveMessage(void *storage, size_t storage_length)
       : MachMessage(storage, storage_length) {}
 
  private:
     DISALLOW_COPY_AND_ASSIGN(MachReceiveMessage);
 };
 
 //==============================================================================
 class MachSendMessage : public MachMessage {
  public:
   explicit MachSendMessage(int32_t message_id);
   MachSendMessage(void *storage, size_t storage_length, int32_t message_id);
 
  private:
   void Initialize(int32_t message_id);
 
   DISALLOW_COPY_AND_ASSIGN(MachSendMessage);
 };
 
 //==============================================================================
-// Represents a mach port for which we have receive rights
+// Represents a Mach port for which we have receive rights
 class ReceivePort {
  public:
-  // Creates a new mach port for receiving messages and registers a name for it
+  // Creates a new Mach port for receiving messages and registers a name for it
   explicit ReceivePort(const char *receive_port_name);
 
-  // Given an already existing mach port, use it.  We take ownership of the
+  // Given an already existing Mach port, use it.  We take ownership of the
   // port and deallocate it in our destructor.
   explicit ReceivePort(mach_port_t receive_port);
 
-  // Create a new mach port for receiving messages
+  // Create a new Mach port for receiving messages
   ReceivePort();
 
   ~ReceivePort();
 
-  // Waits on the mach port until message received or timeout
+  // Waits on the Mach port until message received or timeout.  If |timeout| is
+  // MACH_MSG_TIMEOUT_NONE, this method waits forever.
   kern_return_t WaitForMessage(MachReceiveMessage *out_message,
                                mach_msg_timeout_t timeout);
 
-  // The underlying mach port that we wrap
+  // The underlying Mach port that we wrap
   mach_port_t  GetPort() const { return port_; }
 
  private:
   mach_port_t   port_;
   kern_return_t init_result_;
 
   DISALLOW_COPY_AND_ASSIGN(ReceivePort);
 };
 
 //==============================================================================
-// Represents a mach port for which we have send rights
+// Represents a Mach port for which we have send rights
 class MachPortSender {
  public:
   // get a port with send rights corresponding to a named registered service
   explicit MachPortSender(const char *receive_port_name);
 
 
-  // Given an already existing mach port, use it. Does not take ownership of
+  // Given an already existing Mach port, use it. Does not take ownership of
   // |send_port|.
   explicit MachPortSender(mach_port_t send_port);
 
   kern_return_t SendMessage(MachSendMessage &message,
                             mach_msg_timeout_t timeout);
 
  private:
   mach_port_t   send_port_;
   kern_return_t init_result_;
 
   DISALLOW_COPY_AND_ASSIGN(MachPortSender);
 };
 
 }  // namespace base
 
 #endif // BASE_MACH_IPC_MAC_H_