Make the fuchsia mojo/public repo the source of truth.

mojo/public/cpp/system/handle.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.
-
-#ifndef MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_
-#define MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_
-
-#include <assert.h>
-#include <mojo/result.h>
-#include <mojo/system/handle.h>
-#include <stdint.h>
-
-#include <limits>
-
-#include "mojo/public/cpp/system/macros.h"
-
-namespace mojo {
-
-// OVERVIEW
-//
-// |Handle| and |...Handle|:
-//
-// |Handle| is a simple, copyable wrapper for the C type |MojoHandle| (which is
-// just an integer). Its purpose is to increase type-safety, not provide
-// lifetime management. For the same purpose, we have trivial *subclasses* of
-// |Handle|, e.g., |MessagePipeHandle| and |DataPipeProducerHandle|. |Handle|
-// and its subclasses impose *no* extra overhead over using |MojoHandle|s
-// directly.
-//
-// Note that though we provide constructors for |Handle|/|...Handle| from a
-// |MojoHandle|, we do not provide, e.g., a constructor for |MessagePipeHandle|
-// from a |Handle|. This is for type safety: If we did, you'd then be able to
-// construct a |MessagePipeHandle| from, e.g., a |DataPipeProducerHandle| (since
-// it's a |Handle|).
-//
-// |ScopedHandleBase| and |Scoped...Handle|:
-//
-// |ScopedHandleBase<HandleType>| is a templated scoped wrapper, for the handle
-// types above (in the same sense that a C++11 |unique_ptr<T>| is a scoped
-// wrapper for a |T*|). It provides lifetime management, closing its owned
-// handle on destruction. It also provides (emulated) move semantics, again
-// along the lines of C++11's |unique_ptr| (and exactly like Chromium's
-// |scoped_ptr|).
-//
-// |ScopedHandle| is just (a typedef of) a |ScopedHandleBase<Handle>|.
-// Similarly, |ScopedMessagePipeHandle| is just a
-// |ScopedHandleBase<MessagePipeHandle>|. Etc. Note that a
-// |ScopedMessagePipeHandle| is *not* a (subclass of) |ScopedHandle|.
-//
-// Wrapper functions:
-//
-// We provide simple wrappers for the |Mojo...()| functions (declared in various
-// mojo/public/c/include/mojo/system/*.h -- see those file for details on
-// individual functions).
-//
-// The general guideline is functions that imply ownership transfer of a handle
-// should take (or produce) an appropriate |Scoped...Handle|, while those that
-// don't take a |...Handle|. For example, |CreateMessagePipe()| has two
-// |ScopedMessagePipe| "out" parameters, whereas |Wait()| and |WaitMany()| take
-// |Handle| parameters. Some, have both: e.g., |DuplicatedBuffer()| takes a
-// suitable (unscoped) handle (e.g., |SharedBufferHandle|) "in" parameter and
-// produces a suitable scoped handle (e.g., |ScopedSharedBufferHandle| a.k.a.
-// |ScopedHandleBase<SharedBufferHandle>|) as an "out" parameter.
-//
-// An exception are some of the |...Raw()| functions. E.g., |CloseRaw()| takes a
-// |Handle|, leaving the user to discard the wrapper.
-//
-// ScopedHandleBase ------------------------------------------------------------
-
-// Scoper for the actual handle types defined further below. It's move-only,
-// like the C++11 |unique_ptr|.
-template <class HandleType>
-class ScopedHandleBase {
- public:
-  ScopedHandleBase() {}
-  explicit ScopedHandleBase(HandleType handle) : handle_(handle) {}
-  ~ScopedHandleBase() { CloseIfNecessary(); }
-
-  template <class CompatibleHandleType>
-  explicit ScopedHandleBase(ScopedHandleBase<CompatibleHandleType> other)
-      : handle_(other.release()) {}
-
-  // Move-only constructor and operator=.
-  ScopedHandleBase(ScopedHandleBase&& other) : handle_(other.release()) {}
-  ScopedHandleBase& operator=(ScopedHandleBase&& other) {
-    if (&other != this) {
-      CloseIfNecessary();
-      handle_ = other.release();
-    }
-    return *this;
-  }
-
-  const HandleType& get() const { return handle_; }
-
-  template <typename PassedHandleType>
-  static ScopedHandleBase<HandleType> From(
-      ScopedHandleBase<PassedHandleType> other) {
-    static_assert(
-        sizeof(static_cast<PassedHandleType*>(static_cast<HandleType*>(0))),
-        "HandleType is not a subtype of PassedHandleType");
-    return ScopedHandleBase<HandleType>(
-        static_cast<HandleType>(other.release().value()));
-  }
-
-  void swap(ScopedHandleBase& other) { handle_.swap(other.handle_); }
-
-  HandleType release() MOJO_WARN_UNUSED_RESULT {
-    HandleType rv;
-    rv.swap(handle_);
-    return rv;
-  }
-
-  void reset(HandleType handle = HandleType()) {
-    CloseIfNecessary();
-    handle_ = handle;
-  }
-
-  bool is_valid() const { return handle_.is_valid(); }
-
- private:
-  void CloseIfNecessary() {
-    if (!handle_.is_valid())
-      return;
-    MojoResult result = MojoClose(handle_.value());
-    MOJO_ALLOW_UNUSED_LOCAL(result);
-    assert(result == MOJO_RESULT_OK);
-  }
-
-  HandleType handle_;
-
-  MOJO_MOVE_ONLY_TYPE(ScopedHandleBase);
-};
-
-template <typename HandleType>
-inline ScopedHandleBase<HandleType> MakeScopedHandle(HandleType handle) {
-  return ScopedHandleBase<HandleType>(handle);
-}
-
-// Handle ----------------------------------------------------------------------
-
-const MojoHandle kInvalidHandleValue = MOJO_HANDLE_INVALID;
-
-// Wrapper base class for |MojoHandle|.
-class Handle {
- public:
-  Handle() : value_(kInvalidHandleValue) {}
-  explicit Handle(MojoHandle value) : value_(value) {}
-  ~Handle() {}
-
-  void swap(Handle& other) {
-    MojoHandle temp = value_;
-    value_ = other.value_;
-    other.value_ = temp;
-  }
-
-  bool is_valid() const { return value_ != kInvalidHandleValue; }
-
-  const MojoHandle& value() const { return value_; }
-  MojoHandle* mutable_value() { return &value_; }
-  void set_value(MojoHandle value) { value_ = value; }
-
- private:
-  MojoHandle value_;
-
-  // Copying and assignment allowed.
-};
-
-// Should have zero overhead.
-static_assert(sizeof(Handle) == sizeof(MojoHandle), "Bad size for C++ Handle");
-
-// The scoper should also impose no more overhead.
-typedef ScopedHandleBase<Handle> ScopedHandle;
-static_assert(sizeof(ScopedHandle) == sizeof(Handle),
-              "Bad size for C++ ScopedHandle");
-
-// |Close()| takes ownership of the handle, since it'll invalidate it.
-// Note: There's nothing to do, since the argument will be destroyed when it
-// goes out of scope.
-template <class HandleType>
-inline void Close(ScopedHandleBase<HandleType> /*handle*/) {}
-
-// Most users should typically use |Close()| (above) instead.
-inline MojoResult CloseRaw(Handle handle) {
-  return MojoClose(handle.value());
-}
-
-// Strict weak ordering, so that |Handle|s can be used as keys in |std::map|s,
-inline bool operator<(const Handle a, const Handle b) {
-  return a.value() < b.value();
-}
-
-// Rights and duplication/replacement ------------------------------------------
-
-// |handle| must be valid.
-inline MojoHandleRights GetRights(Handle handle) {
-  assert(handle.is_valid());
-  MojoHandleRights rights = MOJO_HANDLE_RIGHT_NONE;
-  MojoResult result = MojoGetRights(handle.value(), &rights);
-  MOJO_ALLOW_UNUSED_LOCAL(result);
-  assert(result == MOJO_RESULT_OK);
-  return rights;
-}
-
-// |HandleType| should be some subclass of |Handle|; this is templated so that
-// it will work with multiple handle types. |*handle| must be valid. Returns
-// true on success or false on failure (in which case |*handle| is reset).
-template <class HandleType>
-inline bool ReplaceHandleWithReducedRights(ScopedHandleBase<HandleType>* handle,
-                                           MojoHandleRights rights_to_remove) {
-  assert(handle);
-  assert(handle->is_valid());
-  HandleType raw_handle = handle->release();
-  HandleType new_raw_handle;
-  if (MojoReplaceHandleWithReducedRights(raw_handle.value(), rights_to_remove,
-                                         new_raw_handle.mutable_value()) !=
-      MOJO_RESULT_OK) {
-    assert(false);  // This really shouldn't happen.
-    CloseRaw(raw_handle);
-    return false;
-  }
-  // Otherwise, |raw_handle| is invalidated.
-  handle->reset(new_raw_handle);
-  return true;
-}
-
-template <class HandleType>
-inline ScopedHandleBase<HandleType> DuplicateHandleWithReducedRights(
-    HandleType handle,
-    MojoHandleRights rights_to_remove) {
-  assert(handle.is_valid());
-  HandleType new_handle;
-  MojoResult result = MojoDuplicateHandleWithReducedRights(
-      handle.value(), rights_to_remove, new_handle.mutable_value());
-  MOJO_ALLOW_UNUSED_LOCAL(result);
-  assert(result == MOJO_RESULT_OK);
-  return MakeScopedHandle(new_handle);
-}
-
-template <class HandleType>
-inline ScopedHandleBase<HandleType> DuplicateHandle(HandleType handle) {
-  HandleType new_handle;
-  MojoResult result =
-      MojoDuplicateHandle(handle.value(), new_handle.mutable_value());
-  MOJO_ALLOW_UNUSED_LOCAL(result);
-  assert(result == MOJO_RESULT_OK);
-  return MakeScopedHandle(new_handle);
-}
-
-}  // namespace mojo
-
-#endif  // MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_