mojo/public/c/system/handle.h - mojo-tools - Git at Google

 // Copyright 2016 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 Mojo system handle-related declarations/definitions.
 //
 // Note: This header should be compilable as C.

 #ifndef MOJO_PUBLIC_C_SYSTEM_HANDLE_H_
 #define MOJO_PUBLIC_C_SYSTEM_HANDLE_H_

 #include <stdint.h>

 #include "mojo/public/c/system/macros.h"
 #include "mojo/public/c/system/result.h"

 // |MojoHandle|: Handles to Mojo objects.
 //   |MOJO_HANDLE_INVALID| - A value that is never a valid handle.

 typedef uint32_t MojoHandle;

 #define MOJO_HANDLE_INVALID ((MojoHandle)0)

 // |MojoHandleRights|: Rights ("permissions") for handles. Each handle has a
 // bitset of rights flags, which subsequently only be reduced. See each function
 // for details about the right(s) required (some, like |MojoClose()|, require no
 // rights).
 //   |MOJO_HANDLE_RIGHT_NONE| - No rights.
 //   |MOJO_HANDLE_RIGHT_DUPLICATE| - Right to duplicate a handle.
 //   |MOJO_HANDLE_RIGHT_TRANSFER| - Right to transfer a handle (e.g., include in
 //       a message).
 //   |MOJO_HANDLE_RIGHT_READ| - Right to "read" from the handle (e.g., read a
 //       message).
 //   |MOJO_HANDLE_RIGHT_WRITE| - Right to "write" to the handle (e.g., write a
 //       message).
 //   |MOJO_HANDLE_RIGHT_GET_OPTIONS| - Right to get a handle's options.
 //   |MOJO_HANDLE_RIGHT_SET_OPTIONS| - Right to set a handle's options.
 //   |MOJO_HANDLE_RIGHT_MAP_READABLE| - Right to "map" a (e.g., buffer) handle
 //       as readable memory.
 //   |MOJO_HANDLE_RIGHT_MAP_WRITABLE| - Right to "map" a (e.g., buffer) handle
 //       as writable memory.
 //   |MOJO_HANDLE_RIGHT_MAP_EXECUTABLE| - Right to "map" a (e.g., buffer) handle
 //       as executable memory.
 //
 // TODO(vtl): Add rights support/checking to existing handle types.

 typedef uint32_t MojoHandleRights;

 #define MOJO_HANDLE_RIGHT_NONE ((MojoHandleRights)0)
 #define MOJO_HANDLE_RIGHT_DUPLICATE ((MojoHandleRights)1 << 0)
 #define MOJO_HANDLE_RIGHT_TRANSFER ((MojoHandleRights)1 << 1)
 #define MOJO_HANDLE_RIGHT_READ ((MojoHandleRights)1 << 2)
 #define MOJO_HANDLE_RIGHT_WRITE ((MojoHandleRights)1 << 3)
 #define MOJO_HANDLE_RIGHT_GET_OPTIONS ((MojoHandleRights)1 << 4)
 #define MOJO_HANDLE_RIGHT_SET_OPTIONS ((MojoHandleRights)1 << 5)
 #define MOJO_HANDLE_RIGHT_MAP_READABLE ((MojoHandleRights)1 << 6)
 #define MOJO_HANDLE_RIGHT_MAP_WRITABLE ((MojoHandleRights)1 << 7)
 #define MOJO_HANDLE_RIGHT_MAP_EXECUTABLE ((MojoHandleRights)1 << 8)

 // |MojoHandleSignals|: Used to specify signals that can be waited on for a
 // handle (and which can be triggered), e.g., the ability to read or write to
 // the handle.
 //   |MOJO_HANDLE_SIGNAL_NONE| - No flags. |MojoWait()|, etc. will return
 //       |MOJO_RESULT_FAILED_PRECONDITION| if you attempt to wait on this.
 //   |MOJO_HANDLE_SIGNAL_READABLE| - Can read (e.g., a message) from the handle.
 //   |MOJO_HANDLE_SIGNAL_WRITABLE| - Can write (e.g., a message) to the handle.
 //   |MOJO_HANDLE_SIGNAL_PEER_CLOSED| - The peer handle is closed.
 //   |MOJO_HANDLE_SIGNAL_READ_THRESHOLD| - Can read a certain amount of data
 //       from the handle (e.g., a data pipe consumer; see
 //       |MojoDataPipeConsumerOptions|).

 typedef uint32_t MojoHandleSignals;

 #define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0)
 #define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0)
 #define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1)
 #define MOJO_HANDLE_SIGNAL_PEER_CLOSED ((MojoHandleSignals)1 << 2)
 #define MOJO_HANDLE_SIGNAL_READ_THRESHOLD ((MojoHandleSignals)1 << 3)
 #define MOJO_HANDLE_SIGNAL_WRITE_THRESHOLD ((MojoHandleSignals)1 << 4)

 // |MojoHandleSignalsState|: Returned by wait functions to indicate the
 // signaling state of handles. Members are as follows:
 //   - |satisfied signals|: Bitmask of signals that were satisfied at some time
 //         before the call returned.
 //   - |satisfiable signals|: These are the signals that are possible to
 //         satisfy. For example, if the return value was
 //         |MOJO_RESULT_FAILED_PRECONDITION|, you can use this field to
 //         determine which, if any, of the signals can still be satisfied.
 // Note: This struct is not extensible (and only has 32-bit quantities), so it's
 // 32-bit-aligned.

 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(uint32_t) == 4, "uint32_t has weird alignment");
 struct MOJO_ALIGNAS(4) MojoHandleSignalsState {
   MojoHandleSignals satisfied_signals;
   MojoHandleSignals satisfiable_signals;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8,
                    "MojoHandleSignalsState has wrong size");

 MOJO_BEGIN_EXTERN_C

 // |MojoClose()|: Closes the given |handle|.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //   |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction
 //       (that, e.g., may result in it being invalidated, such as being sent in
 //       a message).
 //
 // Concurrent operations on |handle| may succeed (or fail as usual) if they
 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if
 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or
 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after.
 MojoResult MojoClose(MojoHandle handle);  // In.

 // |MojoGetRights()|: Gets the given |handle|'s rights.
 //
 // On success, |*rights| (|rights| must be non-null) will be set to |handle|'s
 // rights.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //   |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction
 //       (that, e.g., may result in it being invalidated, such as being sent in
 //       a message).
 MojoResult MojoGetRights(MojoHandle handle, MojoHandleRights* rights);  // Out.

 // |MojoReduceRights()|: Reduces rights that the given |handle| may have.
 //
 // That is, on success:
 //
 //   new rights = current rights & ~rights_to_remove.
 //
 // Note that it is not an error to "remove" rights that the handle does not
 // (currently) possess.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //   |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction
 //       (that, e.g., may result in it being invalidated, such as being sent in
 //       a message).
 //
 // TODO(vtl): Discuss this API some more. It may be more desirable to replace
 // the handle with a new one (with reduced rights).
 MojoResult MojoReduceRights(MojoHandle handle,
                             MojoHandleRights rights_to_remove);

 // |MojoDuplicateHandleWithReducedRights()|: Duplicates |handle| to a new handle
 // with reduced rights. This requires |handle| to have the
 // |MOJO_HANDLE_RIGHT_DUPLICATE| (note that some handle types may never have
 // this right).
 //
 // The rights for the new handle are determined as in |MojoReduceRights()|. That
 // is, on success:
 //
 //   new handle rights = original handle rights & ~rights_to_remove.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //   |MOJO_RESULT_PERMISSION_DENIED| if |handle| does not have the
 //       |MOJO_HANDLE_RIGHT_DUPLICATE| right.
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
 //       been reached.
 //   |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction
 //       (that, e.g., may result in it being invalidated, such as being sent in
 //       a message).
 MojoResult MojoDuplicateHandleWithReducedRights(
     MojoHandle handle,
     MojoHandleRights rights_to_remove,
     MojoHandle* new_handle);  // Out.

 // |MojoDuplicateHandle()|: Duplicates |handle| to a new handle with equivalent
 // rights. This requires |handle| to have the |MOJO_HANDLE_RIGHT_DUPLICATE|.
 // This is equivalent to |MojoDuplicateHandleWithReducedRights(handle,
 // MOJO_HANDLE_RIGHT_NONE, new_handle)|.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //   |MOJO_RESULT_PERMISSION_DENIED| if |handle| does not have the
 //       |MOJO_HANDLE_RIGHT_DUPLICATE| right.
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
 //       been reached.
 //   |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction
 //       (that, e.g., may result in it being invalidated, such as being sent in
 //       a message).
 MojoResult MojoDuplicateHandle(MojoHandle handle,
                                MojoHandle* new_handle);  // Out.

 MOJO_END_EXTERN_C

 #endif  // MOJO_PUBLIC_C_SYSTEM_HANDLE_H_
	// Copyright 2016 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 Mojo system handle-related declarations/definitions.
	//
	// Note: This header should be compilable as C.

	#ifndef MOJO_PUBLIC_C_SYSTEM_HANDLE_H_
	#define MOJO_PUBLIC_C_SYSTEM_HANDLE_H_

	#include <stdint.h>

	#include "mojo/public/c/system/macros.h"
	#include "mojo/public/c/system/result.h"

	// \|MojoHandle\|: Handles to Mojo objects.
	// \|MOJO_HANDLE_INVALID\| - A value that is never a valid handle.

	typedef uint32_t MojoHandle;

	#define MOJO_HANDLE_INVALID ((MojoHandle)0)

	// \|MojoHandleRights\|: Rights ("permissions") for handles. Each handle has a
	// bitset of rights flags, which subsequently only be reduced. See each function
	// for details about the right(s) required (some, like \|MojoClose()\|, require no
	// rights).
	// \|MOJO_HANDLE_RIGHT_NONE\| - No rights.
	// \|MOJO_HANDLE_RIGHT_DUPLICATE\| - Right to duplicate a handle.
	// \|MOJO_HANDLE_RIGHT_TRANSFER\| - Right to transfer a handle (e.g., include in
	// a message).
	// \|MOJO_HANDLE_RIGHT_READ\| - Right to "read" from the handle (e.g., read a
	// message).
	// \|MOJO_HANDLE_RIGHT_WRITE\| - Right to "write" to the handle (e.g., write a
	// message).
	// \|MOJO_HANDLE_RIGHT_GET_OPTIONS\| - Right to get a handle's options.
	// \|MOJO_HANDLE_RIGHT_SET_OPTIONS\| - Right to set a handle's options.
	// \|MOJO_HANDLE_RIGHT_MAP_READABLE\| - Right to "map" a (e.g., buffer) handle
	// as readable memory.
	// \|MOJO_HANDLE_RIGHT_MAP_WRITABLE\| - Right to "map" a (e.g., buffer) handle
	// as writable memory.
	// \|MOJO_HANDLE_RIGHT_MAP_EXECUTABLE\| - Right to "map" a (e.g., buffer) handle
	// as executable memory.
	//
	// TODO(vtl): Add rights support/checking to existing handle types.

	typedef uint32_t MojoHandleRights;

	#define MOJO_HANDLE_RIGHT_NONE ((MojoHandleRights)0)
	#define MOJO_HANDLE_RIGHT_DUPLICATE ((MojoHandleRights)1 << 0)
	#define MOJO_HANDLE_RIGHT_TRANSFER ((MojoHandleRights)1 << 1)
	#define MOJO_HANDLE_RIGHT_READ ((MojoHandleRights)1 << 2)
	#define MOJO_HANDLE_RIGHT_WRITE ((MojoHandleRights)1 << 3)
	#define MOJO_HANDLE_RIGHT_GET_OPTIONS ((MojoHandleRights)1 << 4)
	#define MOJO_HANDLE_RIGHT_SET_OPTIONS ((MojoHandleRights)1 << 5)
	#define MOJO_HANDLE_RIGHT_MAP_READABLE ((MojoHandleRights)1 << 6)
	#define MOJO_HANDLE_RIGHT_MAP_WRITABLE ((MojoHandleRights)1 << 7)
	#define MOJO_HANDLE_RIGHT_MAP_EXECUTABLE ((MojoHandleRights)1 << 8)

	// \|MojoHandleSignals\|: Used to specify signals that can be waited on for a
	// handle (and which can be triggered), e.g., the ability to read or write to
	// the handle.
	// \|MOJO_HANDLE_SIGNAL_NONE\| - No flags. \|MojoWait()\|, etc. will return
	// \|MOJO_RESULT_FAILED_PRECONDITION\| if you attempt to wait on this.
	// \|MOJO_HANDLE_SIGNAL_READABLE\| - Can read (e.g., a message) from the handle.
	// \|MOJO_HANDLE_SIGNAL_WRITABLE\| - Can write (e.g., a message) to the handle.
	// \|MOJO_HANDLE_SIGNAL_PEER_CLOSED\| - The peer handle is closed.
	// \|MOJO_HANDLE_SIGNAL_READ_THRESHOLD\| - Can read a certain amount of data
	// from the handle (e.g., a data pipe consumer; see
	// \|MojoDataPipeConsumerOptions\|).

	typedef uint32_t MojoHandleSignals;

	#define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0)
	#define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0)
	#define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1)
	#define MOJO_HANDLE_SIGNAL_PEER_CLOSED ((MojoHandleSignals)1 << 2)
	#define MOJO_HANDLE_SIGNAL_READ_THRESHOLD ((MojoHandleSignals)1 << 3)
	#define MOJO_HANDLE_SIGNAL_WRITE_THRESHOLD ((MojoHandleSignals)1 << 4)

	// \|MojoHandleSignalsState\|: Returned by wait functions to indicate the
	// signaling state of handles. Members are as follows:
	// - \|satisfied signals\|: Bitmask of signals that were satisfied at some time
	// before the call returned.
	// - \|satisfiable signals\|: These are the signals that are possible to
	// satisfy. For example, if the return value was
	// \|MOJO_RESULT_FAILED_PRECONDITION\|, you can use this field to
	// determine which, if any, of the signals can still be satisfied.
	// Note: This struct is not extensible (and only has 32-bit quantities), so it's
	// 32-bit-aligned.

	MOJO_STATIC_ASSERT(MOJO_ALIGNOF(uint32_t) == 4, "uint32_t has weird alignment");
	struct MOJO_ALIGNAS(4) MojoHandleSignalsState {
	MojoHandleSignals satisfied_signals;
	MojoHandleSignals satisfiable_signals;
	};
	MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8,
	"MojoHandleSignalsState has wrong size");

	MOJO_BEGIN_EXTERN_C

	// \|MojoClose()\|: Closes the given \|handle\|.
	//
	// Returns:
	// \|MOJO_RESULT_OK\| on success.
	// \|MOJO_RESULT_INVALID_ARGUMENT\| if \|handle\| is not a valid handle.
	// \|MOJO_RESULT_BUSY\| if \|handle\| is currently in use in some transaction
	// (that, e.g., may result in it being invalidated, such as being sent in
	// a message).
	//
	// Concurrent operations on \|handle\| may succeed (or fail as usual) if they
	// happen before the close, be cancelled with result \|MOJO_RESULT_CANCELLED\| if
	// they properly overlap (this is likely the case with \|MojoWait()\|, etc.), or
	// fail with \|MOJO_RESULT_INVALID_ARGUMENT\| if they happen after.
	MojoResult MojoClose(MojoHandle handle); // In.

	// \|MojoGetRights()\|: Gets the given \|handle\|'s rights.
	//
	// On success, \|*rights\| (\|rights\| must be non-null) will be set to \|handle\|'s
	// rights.
	//
	// Returns:
	// \|MOJO_RESULT_OK\| on success.
	// \|MOJO_RESULT_INVALID_ARGUMENT\| if \|handle\| is not a valid handle.
	// \|MOJO_RESULT_BUSY\| if \|handle\| is currently in use in some transaction
	// (that, e.g., may result in it being invalidated, such as being sent in
	// a message).
	MojoResult MojoGetRights(MojoHandle handle, MojoHandleRights* rights); // Out.

	// \|MojoReduceRights()\|: Reduces rights that the given \|handle\| may have.
	//
	// That is, on success:
	//
	// new rights = current rights & ~rights_to_remove.
	//
	// Note that it is not an error to "remove" rights that the handle does not
	// (currently) possess.
	//
	// Returns:
	// \|MOJO_RESULT_OK\| on success.
	// \|MOJO_RESULT_INVALID_ARGUMENT\| if \|handle\| is not a valid handle.
	// \|MOJO_RESULT_BUSY\| if \|handle\| is currently in use in some transaction
	// (that, e.g., may result in it being invalidated, such as being sent in
	// a message).
	//
	// TODO(vtl): Discuss this API some more. It may be more desirable to replace
	// the handle with a new one (with reduced rights).
	MojoResult MojoReduceRights(MojoHandle handle,
	MojoHandleRights rights_to_remove);

	// \|MojoDuplicateHandleWithReducedRights()\|: Duplicates \|handle\| to a new handle
	// with reduced rights. This requires \|handle\| to have the
	// \|MOJO_HANDLE_RIGHT_DUPLICATE\| (note that some handle types may never have
	// this right).
	//
	// The rights for the new handle are determined as in \|MojoReduceRights()\|. That
	// is, on success:
	//
	// new handle rights = original handle rights & ~rights_to_remove.
	//
	// Returns:
	// \|MOJO_RESULT_OK\| on success.
	// \|MOJO_RESULT_INVALID_ARGUMENT\| if \|handle\| is not a valid handle.
	// \|MOJO_RESULT_PERMISSION_DENIED\| if \|handle\| does not have the
	// \|MOJO_HANDLE_RIGHT_DUPLICATE\| right.
	// \|MOJO_RESULT_RESOURCE_EXHAUSTED\| if a process/system/quota/etc. limit has
	// been reached.
	// \|MOJO_RESULT_BUSY\| if \|handle\| is currently in use in some transaction
	// (that, e.g., may result in it being invalidated, such as being sent in
	// a message).
	MojoResult MojoDuplicateHandleWithReducedRights(
	MojoHandle handle,
	MojoHandleRights rights_to_remove,
	MojoHandle* new_handle); // Out.

	// \|MojoDuplicateHandle()\|: Duplicates \|handle\| to a new handle with equivalent
	// rights. This requires \|handle\| to have the \|MOJO_HANDLE_RIGHT_DUPLICATE\|.
	// This is equivalent to \|MojoDuplicateHandleWithReducedRights(handle,
	// MOJO_HANDLE_RIGHT_NONE, new_handle)\|.
	//
	// Returns:
	// \|MOJO_RESULT_OK\| on success.
	// \|MOJO_RESULT_INVALID_ARGUMENT\| if \|handle\| is not a valid handle.
	// \|MOJO_RESULT_PERMISSION_DENIED\| if \|handle\| does not have the
	// \|MOJO_HANDLE_RIGHT_DUPLICATE\| right.
	// \|MOJO_RESULT_RESOURCE_EXHAUSTED\| if a process/system/quota/etc. limit has
	// been reached.
	// \|MOJO_RESULT_BUSY\| if \|handle\| is currently in use in some transaction
	// (that, e.g., may result in it being invalidated, such as being sent in
	// a message).
	MojoResult MojoDuplicateHandle(MojoHandle handle,
	MojoHandle* new_handle); // Out.

	MOJO_END_EXTERN_C

	#endif // MOJO_PUBLIC_C_SYSTEM_HANDLE_H_