Add NotifyServer and its test

util/mach/notify_server.h

+// Copyright 2014 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_
+#define CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_
+
+#include <mach/mach.h>
+
+#include <set>
+
+#include "base/basictypes.h"
+#include "util/mach/mach_message_server.h"
+
+namespace crashpad {
+
+//! \brief A server interface for the `notify` Mach subsystem.
+//!
+//! The <a
+//! href="https://lists.apple.com/archives/darwin-development/2001/Sep/msg00451.html">mach
+//! port notifications</a> thread on the <a
+//! href="https://lists.apple.com/archives/darwin-development/">darwin-development</a>
+//! mailing list (now known as <a
+//! href="https://lists.apple.com/mailman/listinfo/darwin-dev">darwin-dev</a>)
+//! is good background for the various notification types.
+class NotifyServer : public MachMessageServer::Interface {
+ public:
+  //! \brief An interface that the different request messages that are a part of
+  //!     the `notify` Mach subsystem can be dispatched to.
+  class Interface {
+   public:
+    //! \brief Handles port-deleted notifications sent by
+    //!     `mach_notify_port_deleted()`.
+    //!
+    //! A port-deleted notification is generated when a port with a dead-name
+    //! notification request is destroyed and the port name becomes available
+    //! for reuse.
+    //!
+    //! This behaves equivalently to a `do_mach_notify_port_deleted()` function
+    //! used with `notify_server()`.
+    //!
+    //! \param[in] notify The Mach port that the notification was sent to.
+    //! \param[in] name The name that formerly referenced the deleted port. When
+    //!     this method is called, \a name no longer corresponds to the port
+    //!     that has been deleted, and may be reused for another purpose.
+    //! \param[in] trailer The trailer received with the notification message.
+    virtual kern_return_t DoMachNotifyPortDeleted(
+        notify_port_t notify,
+        mach_port_name_t name,
+        const mach_msg_trailer_t* trailer) = 0;
+
+    //! \brief Handles port-destroyed notifications sent by
+    //!     `mach_notify_port_destroyed()`.
+    //!
+    //! A port-destroyed notification is generated when a receive right with a
+    //! port-destroyed notification request is destroyed. Rather than destroying
+    //! the receive right, it is transferred via this notification’s \a rights
+    //! parameter.
+    //!
+    //! This behaves equivalently to a `do_mach_notify_port_destroyed()`
+    //! function used with `notify_server()`.
+    //!
+    //! \param[in] notify The Mach port that the notification was sent to.
+    //! \param[in] rights A receive right for the port that would have been
+    //!     destroyed. The callee takes ownership of this port, however, if the
+    //!     callee does not wish to take ownership, it may set \a
+    //!     destroy_request to `true`.
+    //! \param[in] trailer The trailer received with the notification message.
+    //! \param[out] destroy_request `true` if the request message is to be
+    //!     destroyed even when this method returns success. See
+    //!     MachMessageServer::Interface.
+    virtual kern_return_t DoMachNotifyPortDestroyed(
+        notify_port_t notify,
+        mach_port_t rights,
+        const mach_msg_trailer_t* trailer,
+        bool* destroy_request) = 0;
+
+    //! \brief Handles no-senders notifications sent by
+    //!     `mach_notify_no_senders()`.
+    //!
+    //! A no-senders notification is generated when a receive right with a
+    //! no-senders notification request loses its last corresponding send right.
+    //!
+    //! This behaves equivalently to a `do_mach_notify_no_senders()` function
+    //! used with `notify_server()`.
+    //!
+    //! \param[in] notify The Mach port that the notification was sent to.
+    //! \param[in] mscount The value of the sender-less port’s make-send count
+    //!     at the time the notification was generated.
+    //! \param[in] trailer The trailer received with the notification message.
+    virtual kern_return_t DoMachNotifyNoSenders(
+        notify_port_t notify,
+        mach_port_mscount_t mscount,
+        const mach_msg_trailer_t* trailer) = 0;
+
+    //! \brief Handles send-once notifications sent by
+    //!     `mach_notify_send_once()`.
+    //!
+    //! A send-once notification is generated when a send-once right is
+    //! destroyed without being used.
+    //!
+    //! This behaves equivalently to a `do_mach_notify_send_once()` function
+    //! used with `notify_server()`.
+    //!
+    //! \param[in] notify The Mach port that the notification was sent to.
+    //! \param[in] trailer The trailer received with the notification message.
+    //!
+    //! \note Unlike the other notifications in the `notify` subsystem,
+    //!     send-once notifications are not generated as a result of a
+    //!     notification request, but are generated any time a send-once right
+    //!     is destroyed rather than being used. The notification is sent via
+    //!     the send-once right to its receiver. These notifications are more
+    //!     useful for clients, not servers. Send-once notifications are
+    //!     normally handled by MIG-generated client routines, which make
+    //!     send-once rights for their reply ports and interpret send-once
+    //!     notifications as a signal that there will be no reply. Although not
+    //!     expected to be primarily useful for servers, this method is provided
+    //!     because send-once notifications are defined as a part of the
+    //!     `notify` subsystem.
+    virtual kern_return_t DoMachNotifySendOnce(
+        notify_port_t notify,
+        const mach_msg_trailer_t* trailer) = 0;
+
+    //! \brief Handles dead-name notifications sent by
+    //!     `mach_notify_dead_name()`.
+    //!
+    //! A dead-name notification is generated when a port with a dead-name
+    //! notification request is destroyed and the right becomes a dead name.
+    //!
+    //! This behaves equivalently to a `do_mach_notify_dead_name()` function
+    //! used with `notify_server()`.
+    //!
+    //! \param[in] notify The Mach port that the notification was sent to.
+    //! \param[in] name The dead name. Although this is transferred as a
+    //!     `mach_port_name_t` and not a `mach_port_t`, the callee assumes an
+    //!     additional reference to this port when this method is called. See
+    //!     the note below.
+    //! \param[in] trailer The trailer received with the notification message.
+    //!
+    //! \note When a dead-name notification is generated, the user reference
+    //!     count of the dead name is incremented. A send right with one
+    //!     reference that becomes a dead name will have one dead-name
+    //!     reference, and the dead-name notification will add another dead-name
+    //!     reference, for a total of 2. DoMachNotifyDeadName() implementations
+    //!     must take care to deallocate this extra reference. There is no \a
+    //!     destroy_request parameter to simplify this operation because
+    //!     dead-name notifications carry a port name only (\a name is of type
+    //!     `mach_port_name_t`) without transferring port rights, and are thus
+    //!     not complex Mach messages.
+    virtual kern_return_t DoMachNotifyDeadName(
+        notify_port_t notify,
+        mach_port_name_t name,
+        const mach_msg_trailer_t* trailer) = 0;
+
+   protected:
+    ~Interface() {}
+  };
+
+  //! \brief Constructs an object of this class.
+  //!
+  //! \param[in] interface The interface to dispatch requests to. Weak.
+  explicit NotifyServer(Interface* interface);
+
+  // MachMessageServer::Interface:
+
+  bool MachMessageServerFunction(const mach_msg_header_t* in_header,
+                                 mach_msg_header_t* out_header,
+                                 bool* destroy_complex_request) override;
+
+  std::set<mach_msg_id_t> MachMessageServerRequestIDs() override;
+
+  mach_msg_size_t MachMessageServerRequestSize() override;
+  mach_msg_size_t MachMessageServerReplySize() override;
+
+ private:
+  Interface* interface_;  // weak
+
+  DISALLOW_COPY_AND_ASSIGN(NotifyServer);
+};
+
+}  // namespace crashpad
+
+#endif  // CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_