[mojo-edk] Add explicit message object APIs

mojo/public/c/system/message_pipe.h

 // Copyright 2014 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.
 
 // This file contains types/constants and functions specific to message pipes.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
@@ skipping 61 matching lines @@
 typedef uint32_t MojoReadMessageFlags;
 
 #ifdef __cplusplus
 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0;
 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0;
 #else
 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags)0)
 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0)
 #endif
 
+// |MojoCreateMessageFlags|: Used to specify different options for
+// |MojoCreateMessage()|.
+//   |MOJO_CREATE_MESSAGE_FLAG_NONE| - No flags; default mode.
+
+typedef uint32_t MojoCreateMessageFlags;
+
+#ifdef __cplusplus
+const MojoCreateMessageFlags MOJO_CREATE_MESSAGE_FLAG_NONE = 0;
+#else
+#define MOJO_CREATE_MESSAGE_FLAG_NONE ((MojoCreateMessageFlags)0)
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // Note: See the comment in functions.h about the meaning of the "optional"
 // label for pointer parameters.
 
 // Creates a message pipe, which is a bidirectional communication channel for
 // framed data (i.e., messages). Messages can contain plain data and/or Mojo
 // handles.
@@ skipping 18 matching lines @@
 // with message data specified by |bytes| of size |num_bytes| and attached
 // handles specified by |handles| of count |num_handles|, and options specified
 // by |flags|. If there is no message data, |bytes| may be null, in which case
 // |num_bytes| must be zero. If there are no attached handles, |handles| may be
 // null, in which case |num_handles| must be zero.
 //
 // If handles are attached, on success the handles will no longer be valid (the
 // receiver will receive equivalent, but logically different, handles). Handles
 // to be sent should not be in simultaneous use (e.g., on another thread).
 //
+// DEPRECATED: This function will be removed. Use |MojoWriteMessageNew()|.

[Anand Mistry (off Chromium), 2016/04/19 12:57:36]

I'd prefer if these weren't marked as deprecated just yet. As we discussed, the
new API might change significantly and I don't think it's wise to discourage the
current API just yet.

I know, there are very few users of the EDK's API, but still...

[Ken Rockot(use gerrit already), 2016/04/19 18:11:25]

OK - Removed DEPRECATED notices and TODOs for now.

+//
 // Returns:
 //   |MOJO_RESULT_OK| on success (i.e., the message was enqueued).
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if
 //       |message_pipe_handle| is not a valid handle, or some of the
 //       requirements above are not satisfied).
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or
 //       the number of handles to send is too large (TODO(vtl): reconsider the
 //       latter case).
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
 //       Note that closing an endpoint is not necessarily synchronous (e.g.,
 //       across processes), so this function may succeed even if the other
 //       endpoint has been closed (in which case the message would be dropped).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 //   |MOJO_RESULT_BUSY| if some handle to be sent is currently in use.
 //
 // TODO(vtl): Add a notion of capacity for message pipes, and return
 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full.
 MOJO_SYSTEM_EXPORT MojoResult
     MojoWriteMessage(MojoHandle message_pipe_handle,
                      const void* bytes,  // Optional.
                      uint32_t num_bytes,
                      const MojoHandle* handles,  // Optional.
                      uint32_t num_handles,
                      MojoWriteMessageFlags flags);
 
+// Writes a message to the message pipe endpoint given by |message_pipe_handle|.
+//
+// |message|: A message object created by |MojoCreateMessage()|. Ownership of
+//     the message is passed into Mojo.
+//
+//
+// TODO(rockot/amistry): Rename this to |MojoWriteMessage()| once that API is
+// no longer used in its current form.
+//
+// Returns results corresponding to |MojoWriteMessage()| above.
+MOJO_SYSTEM_EXPORT MojoResult
+    MojoWriteMessageNew(MojoHandle message_pipe_handle,
+                        void* message,
+                        MojoWriteMessageFlags);
+
 // Reads the next message from a message pipe, or indicates the size of the
 // message if it cannot fit in the provided buffers. The message will be read
 // in its entirety or not at all; if it is not, it will remain enqueued unless
 // the |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed. At most one
 // message will be consumed from the queue, and the return value will indicate
 // whether a message was successfully read.
 //
 // |num_bytes| and |num_handles| are optional in/out parameters that on input
 // must be set to the sizes of the |bytes| and |handles| arrays, and on output
 // will be set to the actual number of bytes or handles contained in the
 // message (even if the message was not retrieved due to being too large).
 // Either |num_bytes| or |num_handles| may be null if the message is not
 // expected to contain the corresponding type of data, but such a call would
 // fail with |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message in fact did
 // contain that type of data.
 //
 // |bytes| and |handles| will receive the contents of the message, if it is
 // retrieved. Either or both may be null, in which case the corresponding size
 // parameter(s) must also be set to zero or passed as null.
 //
+// DEPRECATED: This function will be removed. Use |MojoReadMessageNew()|.
+//
 // Returns:
 //   |MOJO_RESULT_OK| on success (i.e., a message was actually read).
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid.
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message was too large to fit in the
 //       provided buffer(s). The message will have been left in the queue or
 //       discarded, depending on flags.
 //   |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read.
 //
 // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should
 // distinguish this from the hitting-system-limits case.
 MOJO_SYSTEM_EXPORT MojoResult
     MojoReadMessage(MojoHandle message_pipe_handle,
                     void* bytes,            // Optional out.
                     uint32_t* num_bytes,    // Optional in/out.
                     MojoHandle* handles,    // Optional out.
                     uint32_t* num_handles,  // Optional in/out.
                     MojoReadMessageFlags flags);
 
+// Reads the next message from a message pipe and returns an address to a
+// message containing the message bytes. The returned message must eventually be
+// freed using |MojoDestroyMessage()|.
+//
+// Message payload can be accessed using |MojoGetMessageBuffer()|.
+//
+//   |message_pipe_handle|, |num_bytes|, |handles|, |num_handles|, and |flags|
+//       correspond to their use in |MojoReadMessage()| above, with the
+//       exception that |num_bytes| is only an output argument.
+//   |message| must be non-null unless |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| is
+//       set in flags.
+//
+// Return values correspond to the return values for |MojoReadMessage()| above.
+// On success (MOJO_RESULT_OK), |*message| will contain the address of a
+// message object which may be passed to |MojoGetMessageBuffer()| and/or
+// |MojoDestroyMessage()|.
+//
+// TODO(rockot/amistry): Rename this to |MojoReadMessage()| once that API is no
+// longer used in its current form.
+MOJO_SYSTEM_EXPORT MojoResult
+    MojoReadMessageNew(MojoHandle message_pipe_handle,
+                       void** message,         // Optional out.
+                       uint32_t* num_bytes,    // Optional out.
+                       MojoHandle* handles,    // Optional out.
+                       uint32_t* num_handles,  // Optional in/out.
+                       MojoReadMessageFlags flags);
+
 // Fuses two message pipe endpoints together. Given two pipes:
 //
 //     A <-> B    and    C <-> D
 //
 // Fusing handle B and handle C results in a single pipe:
 //
 //     A <-> D
 //
 // Handles B and C are ALWAYS closed. Any unread messages at C will eventually
 // be delivered to A, and any unread messages at B will eventually be delivered
 // to D.
 //
 // NOTE: A handle may only be fused if it is an open message pipe handle which
 // has not been written to.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_FAILED_PRECONDITION| if both handles were valid message pipe
 //       handles but could not be merged (e.g. one of them has been written to).
 //   |MOJO_INVALID_ARGUMENT| if either handle is not a fusable message pipe
 //       handle.
 MOJO_SYSTEM_EXPORT MojoResult
     MojoFuseMessagePipes(MojoHandle handle0, MojoHandle handle1);
 
+// Allocates a new message whose ownership may be passed to
+// |MojoWriteMessageNew()|. Use |MojoGetMessageBuffer()| to retrieve the address
+// of the mutable message payload.
+//
+// |num_bytes|: The size of the message payload in bytes.
+// |handles|: An array of handles to transfer in the message. This takes
+//     ownership of and invalidates all contained handles. Must be null if and
+//     only if |num_handles| is 0.
+// |num_handles|: The number of handles contained in |handles|.
+// |flags|: Must be |MOJO_CREATE_MESSAGE_FLAG_NONE|.
+// |message|: The address of a pointer to be filled with the new message's
+//     address. Must be non-null.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if the message was successfully allocated. In this case
+//       |*message| will be populated with the address of an allocated message
+//       large enough to hold at least |num_bytes| contiguous bytes.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if one or more handles in |handles| was
+//       invalid, or |handles| was null with a non-zero |num_handles|.
+//   |MOJO_RESULT_RESOURCE_EXHAUSTED| if allocation failed because either
+//       |num_bytes| or |num_handles| exceeds an implementation-defined maximum.
+//   |MOJO_RESULT_BUSY| if one or more handles in |handles| cannot be sent at
+//       the time of this call.
+//
+// Only upon successful message allocation will all handles in |handles| be
+// transferred into the message and invalidated.
+MOJO_SYSTEM_EXPORT MojoResult
+MojoCreateMessage(uint32_t num_bytes,
+                  const MojoHandle* handles,
+                  uint32_t num_handles,
+                  MojoCreateMessageFlags flags,
+                  void** message);  // Out

[Anand Mistry (off Chromium), 2016/04/19 12:57:36]

Since you're not meant to directly read/write the message memory, it's really
just an opaque handle to a messgae and I'd prefer if that was more explicit by
having this be a handle type instead of a void*.

i.e:
typedef uintptr_t MessageHandle;

[Ken Rockot(use gerrit already), 2016/04/19 18:11:25]

Done.

+
+// Destroys a message allocated by |MojoCreateMessage()| or
+// |MojoReadMessageNew()|.
+//
+// |message|: The address of the message to destroy. This must correspond to a
+//     message previously created by |MojoCreateMessage()| or
+//     |MojoReadMessageNew()|. Note that if the message has already been passed
+//     to |MojoWriteMessageNew()| it should NOT also be destroyed with this API.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |message| was valid and has been destroyed.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |message| was not a valid message object.
+MOJO_SYSTEM_EXPORT MojoResult MojoDestroyMessage(void* message);

[Anand Mistry (off Chromium), 2016/04/19 12:57:36]

nit: In my experience (mainly media APIs), buffer APIs generally "release" and
"return" buffers instead of "destroying" them.

[Ken Rockot(use gerrit already), 2016/04/19 18:11:25]

I left the names unchanged for now. In general I think Acquire and Release would
be good complementary verbs which better than Create and Destroy. However, I
don't like the idea of using "Acquire" - I think it would be confusing. I do
like "Alloc" or "Allocate", but then a better complementary verb just by
convention would be "Free" IMHO.

So I wanted to get your opinion before making any changes: How do you feel about
MojoAllocMessage (or MojoAllocateMessage) and MojoFreeMessage? Alternatively,
can you think of a verb better than Acquire to complement Release?

[Anand Mistry (off Chromium), 2016/04/21 12:19:42]

I like Alloc/Free better than Create/Destroy. I don't have a strong opinion on
alloc versus allocate.

[Ken Rockot(use gerrit already), 2016/04/21 16:47:40]

Done. MojoAllocMessage and MojoFreeMessage.

+
+// Retrieves the address of mutable message bytes for a message created by
+// either |MojoCreateMessage()| or |MojoReadMessageNew()|.
+//
+// |message|: The message object.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |message| is a valid message object. |*buffer| will
+//       be updated to point to mutable message bytes.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |message| is not a valid message object.
+MOJO_SYSTEM_EXPORT MojoResult MojoGetMessageBuffer(void* message,
+                                                   void** buffer);  // Out
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_