diff options
Diffstat (limited to 'mojo/public/c/system/message_pipe.h')
| -rw-r--r-- | mojo/public/c/system/message_pipe.h | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/mojo/public/c/system/message_pipe.h b/mojo/public/c/system/message_pipe.h new file mode 100644 index 0000000000..b759bc73db --- /dev/null +++ b/mojo/public/c/system/message_pipe.h @@ -0,0 +1,341 @@ +// 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_ + +#include <stdint.h> + +#include "mojo/public/c/system/macros.h" +#include "mojo/public/c/system/system_export.h" +#include "mojo/public/c/system/types.h" + +// |MojoMessageHandle|: Used to refer to message objects created by +// |MojoAllocMessage()| and transferred by |MojoWriteMessageNew()| or +// |MojoReadMessageNew()|. + +typedef uintptr_t MojoMessageHandle; + +#ifdef __cplusplus +const MojoMessageHandle MOJO_MESSAGE_HANDLE_INVALID = 0; +#else +#define MOJO_MESSAGE_HANDLE_INVALID ((MojoMessageHandle)0) +#endif + +// |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a +// message pipe to |MojoCreateMessagePipe()|. +// |uint32_t struct_size|: Set to the size of the +// |MojoCreateMessagePipeOptions| struct. (Used to allow for future +// extensions.) +// |MojoCreateMessagePipeOptionsFlags flags|: Used to specify different modes +// of operation. +// |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. + +typedef uint32_t MojoCreateMessagePipeOptionsFlags; + +#ifdef __cplusplus +const MojoCreateMessagePipeOptionsFlags + MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0; +#else +#define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \ + ((MojoCreateMessagePipeOptionsFlags)0) +#endif + +MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment"); +struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions { + uint32_t struct_size; + MojoCreateMessagePipeOptionsFlags flags; +}; +MOJO_STATIC_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8, + "MojoCreateMessagePipeOptions has wrong size"); + +// |MojoWriteMessageFlags|: Used to specify different modes to +// |MojoWriteMessage()|. +// |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. + +typedef uint32_t MojoWriteMessageFlags; + +#ifdef __cplusplus +const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0; +#else +#define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags)0) +#endif + +// |MojoReadMessageFlags|: Used to specify different modes to +// |MojoReadMessage()|. +// |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode. +// |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read +// for whatever reason (e.g., the caller-supplied buffer is too small), +// discard the message (i.e., simply dequeue it). + +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 + +// |MojoAllocMessageFlags|: Used to specify different options for +// |MojoAllocMessage()|. +// |MOJO_ALLOC_MESSAGE_FLAG_NONE| - No flags; default mode. + +typedef uint32_t MojoAllocMessageFlags; + +#ifdef __cplusplus +const MojoAllocMessageFlags MOJO_ALLOC_MESSAGE_FLAG_NONE = 0; +#else +#define MOJO_ALLOC_MESSAGE_FLAG_NONE ((MojoAllocMessageFlags)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. +// +// |options| may be set to null for a message pipe with the default options. +// +// On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to +// handles for the two endpoints (ports) for the message pipe. +// +// Returns: +// |MOJO_RESULT_OK| on success. +// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., +// |*options| is invalid). +// |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has +// been reached. +MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( + const struct MojoCreateMessagePipeOptions* options, // Optional. + MojoHandle* message_pipe_handle0, // Out. + MojoHandle* message_pipe_handle1); // Out. + +// Writes a message to the message pipe endpoint given by |message_pipe_handle|, +// 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, the handles will no longer be valid (on success the +// receiver will receive equivalent, but logically different, handles). Handles +// to be sent should not be in simultaneous use (e.g., on another thread). +// +// 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 allocated by |MojoAllocMessage()|. Ownership of +// the message is passed into Mojo. +// +// Returns results corresponding to |MojoWriteMessage()| above. +MOJO_SYSTEM_EXPORT MojoResult + MojoWriteMessageNew(MojoHandle message_pipe_handle, + MojoMessageHandle 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. +// +// 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 a message containing +// the message bytes. The returned message must eventually be freed using +// |MojoFreeMessage()|. +// +// 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 a handle to a message +// object which may be passed to |MojoGetMessageBuffer()|. The caller owns the +// message object and is responsible for freeing it via |MojoFreeMessage()|. +MOJO_SYSTEM_EXPORT MojoResult + MojoReadMessageNew(MojoHandle message_pipe_handle, + MojoMessageHandle* 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 handle to be filled with the allocated message's +// handle. Must be non-null. +// +// Returns: +// |MOJO_RESULT_OK| if the message was successfully allocated. In this case +// |*message| will be populated with a handle to an allocated message +// with a buffer large enough to hold |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 +MojoAllocMessage(uint32_t num_bytes, + const MojoHandle* handles, + uint32_t num_handles, + MojoAllocMessageFlags flags, + MojoMessageHandle* message); // Out + +// Frees a message allocated by |MojoAllocMessage()| or |MojoReadMessageNew()|. +// +// |message|: The message to free. This must correspond to a message previously +// allocated by |MojoAllocMessage()| or |MojoReadMessageNew()|. Note that if +// the message has already been passed to |MojoWriteMessageNew()| it should +// NOT also be freed with this API. +// +// Returns: +// |MOJO_RESULT_OK| if |message| was valid and has been freed. +// |MOJO_RESULT_INVALID_ARGUMENT| if |message| was not a valid message. +MOJO_SYSTEM_EXPORT MojoResult MojoFreeMessage(MojoMessageHandle message); + +// Retrieves the address of mutable message bytes for a message allocated by +// either |MojoAllocMessage()| or |MojoReadMessageNew()|. +// +// 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. +// +// NOTE: A returned buffer address is always guaranteed to be 8-byte aligned. +MOJO_SYSTEM_EXPORT MojoResult MojoGetMessageBuffer(MojoMessageHandle message, + void** buffer); // Out + +// Notifies the system that a bad message was received on a message pipe, +// according to whatever criteria the caller chooses. This ultimately tries to +// notify the embedder about the bad message, and the embedder may enforce some +// policy for dealing with the source of the message (e.g. close the pipe, +// terminate, a process, etc.) The embedder may not be notified if the calling +// process has lost its connection to the source process. +// +// |message|: The message to report as bad. This must have come from a call to +// |MojoReadMessageNew()|. +// |error|: An error string which may provide the embedder with context when +// notified of this error. +// |error_num_bytes|: The length of |error| in bytes. +// +// Returns: +// |MOJO_RESULT_OK| if successful. +// |MOJO_RESULT_INVALID_ARGUMENT| if |message| is not a valid message. +MOJO_SYSTEM_EXPORT MojoResult +MojoNotifyBadMessage(MojoMessageHandle message, + const char* error, + size_t error_num_bytes); + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |