src/mojo/public/cpp/system/handle.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_
   6 #define MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_
   7
   8 #include <assert.h>
   9 #include <limits>
  10
  11 #include "mojo/public/c/system/functions.h"
  12 #include "mojo/public/c/system/types.h"
  13 #include "mojo/public/cpp/system/macros.h"
  14
  15 namespace mojo {
  16
  17 // OVERVIEW
  18 //
  19 // |Handle| and |...Handle|:
  20 //
  21 // |Handle| is a simple, copyable wrapper for the C type |MojoHandle| (which is
  22 // just an integer). Its purpose is to increase type-safety, not provide
  23 // lifetime management. For the same purpose, we have trivial *subclasses* of
  24 // |Handle|, e.g., |MessagePipeHandle| and |DataPipeProducerHandle|. |Handle|
  25 // and its subclasses impose *no* extra overhead over using |MojoHandle|s
  26 // directly.
  27 //
  28 // Note that though we provide constructors for |Handle|/|...Handle| from a
  29 // |MojoHandle|, we do not provide, e.g., a constructor for |MessagePipeHandle|
  30 // from a |Handle|. This is for type safety: If we did, you'd then be able to
  31 // construct a |MessagePipeHandle| from, e.g., a |DataPipeProducerHandle| (since
  32 // it's a |Handle|).
  33 //
  34 // |ScopedHandleBase| and |Scoped...Handle|:
  35 //
  36 // |ScopedHandleBase<HandleType>| is a templated scoped wrapper, for the handle
  37 // types above (in the same sense that a C++11 |unique_ptr<T>| is a scoped
  38 // wrapper for a |T*|). It provides lifetime management, closing its owned
  39 // handle on destruction. It also provides (emulated) move semantics, again
  40 // along the lines of C++11's |unique_ptr| (and exactly like Chromium's
  41 // |scoped_ptr|).
  42 //
  43 // |ScopedHandle| is just (a typedef of) a |ScopedHandleBase<Handle>|.
  44 // Similarly, |ScopedMessagePipeHandle| is just a
  45 // |ScopedHandleBase<MessagePipeHandle>|. Etc. Note that a
  46 // |ScopedMessagePipeHandle| is *not* a (subclass of) |ScopedHandle|.
  47 //
  48 // Wrapper functions:
  49 //
  50 // We provide simple wrappers for the |Mojo...()| functions (in
  51 // mojo/public/c/system/core.h -- see that file for details on individual
  52 // functions).
  53 //
  54 // The general guideline is functions that imply ownership transfer of a handle
  55 // should take (or produce) an appropriate |Scoped...Handle|, while those that
  56 // don't take a |...Handle|. For example, |CreateMessagePipe()| has two
  57 // |ScopedMessagePipe| "out" parameters, whereas |Wait()| and |WaitMany()| take
  58 // |Handle| parameters. Some, have both: e.g., |DuplicatedBuffer()| takes a
  59 // suitable (unscoped) handle (e.g., |SharedBufferHandle|) "in" parameter and
  60 // produces a suitable scoped handle (e.g., |ScopedSharedBufferHandle| a.k.a.
  61 // |ScopedHandleBase<SharedBufferHandle>|) as an "out" parameter.
  62 //
  63 // An exception are some of the |...Raw()| functions. E.g., |CloseRaw()| takes a
  64 // |Handle|, leaving the user to discard the handle.
  65 //
  66 // More significantly, |WriteMessageRaw()| exposes the full API complexity of
  67 // |MojoWriteMessage()| (but doesn't require any extra overhead). It takes a raw
  68 // array of |Handle|s as input, and takes ownership of them (i.e., invalidates
  69 // them) on *success* (but not on failure). There are a number of reasons for
  70 // this. First, C++03 |std::vector|s cannot contain the move-only
  71 // |Scoped...Handle|s. Second, |std::vector|s impose extra overhead
  72 // (necessitating heap-allocation of the buffer). Third, |std::vector|s wouldn't
  73 // provide the desired level of flexibility/safety: a vector of handles would
  74 // have to be all of the same type (probably |Handle|/|ScopedHandle|). Fourth,
  75 // it's expected to not be used directly, but instead be used by generated
  76 // bindings.
  77 //
  78 // Other |...Raw()| functions expose similar rough edges, e.g., dealing with raw
  79 // pointers (and lengths) instead of taking |std::vector|s or similar.
  80
  81 // ScopedHandleBase ------------------------------------------------------------
  82
  83 // Scoper for the actual handle types defined further below. It's move-only,
  84 // like the C++11 |unique_ptr|.
  85 template <class HandleType>
  86 class ScopedHandleBase {
  87   MOJO_MOVE_ONLY_TYPE_FOR_CPP_03(ScopedHandleBase, RValue)
  88
  89  public:
  90   ScopedHandleBase() {}
  91   explicit ScopedHandleBase(HandleType handle) : handle_(handle) {}
  92   ~ScopedHandleBase() { CloseIfNecessary(); }
  93
  94   template <class CompatibleHandleType>
  95   explicit ScopedHandleBase(ScopedHandleBase<CompatibleHandleType> other)
  96       : handle_(other.release()) {
  97   }
  98
  99   // Move-only constructor and operator=.
 100   ScopedHandleBase(RValue other) : handle_(other.object->release()) {}
 101   ScopedHandleBase& operator=(RValue other) {
 102     if (other.object != this) {
 103       CloseIfNecessary();
 104       handle_ = other.object->release();
 105     }
 106     return *this;
 107   }
 108
 109   const HandleType& get() const { return handle_; }
 110
 111   template <typename PassedHandleType>
 112   static ScopedHandleBase<HandleType> From(
 113       ScopedHandleBase<PassedHandleType> other) {
 114     MOJO_COMPILE_ASSERT(
 115         sizeof(static_cast<PassedHandleType*>(static_cast<HandleType*>(0))),
 116         HandleType_is_not_a_subtype_of_PassedHandleType);
 117     return ScopedHandleBase<HandleType>(
 118         static_cast<HandleType>(other.release().value()));
 119   }
 120
 121   void swap(ScopedHandleBase& other) {
 122     handle_.swap(other.handle_);
 123   }
 124
 125   HandleType release() MOJO_WARN_UNUSED_RESULT {
 126     HandleType rv;
 127     rv.swap(handle_);
 128     return rv;
 129   }
 130
 131   void reset(HandleType handle = HandleType()) {
 132     CloseIfNecessary();
 133     handle_ = handle;
 134   }
 135
 136   bool is_valid() const {
 137     return handle_.is_valid();
 138   }
 139
 140  private:
 141   void CloseIfNecessary() {
 142     if (!handle_.is_valid())
 143       return;
 144     MojoResult result MOJO_ALLOW_UNUSED = MojoClose(handle_.value());
 145     assert(result == MOJO_RESULT_OK);
 146   }
 147
 148   HandleType handle_;
 149 };
 150
 151 template <typename HandleType>
 152 inline ScopedHandleBase<HandleType> MakeScopedHandle(HandleType handle) {
 153   return ScopedHandleBase<HandleType>(handle);
 154 }
 155
 156 // Handle ----------------------------------------------------------------------
 157
 158 const MojoHandle kInvalidHandleValue = MOJO_HANDLE_INVALID;
 159
 160 // Wrapper base class for |MojoHandle|.
 161 class Handle {
 162  public:
 163   Handle() : value_(kInvalidHandleValue) {}
 164   explicit Handle(MojoHandle value) : value_(value) {}
 165   ~Handle() {}
 166
 167   void swap(Handle& other) {
 168     MojoHandle temp = value_;
 169     value_ = other.value_;
 170     other.value_ = temp;
 171   }
 172
 173   bool is_valid() const {
 174     return value_ != kInvalidHandleValue;
 175   }
 176
 177   const MojoHandle& value() const { return value_; }
 178   MojoHandle* mutable_value() { return &value_; }
 179   void set_value(MojoHandle value) { value_ = value; }
 180
 181  private:
 182   MojoHandle value_;
 183
 184   // Copying and assignment allowed.
 185 };
 186
 187 // Should have zero overhead.
 188 MOJO_COMPILE_ASSERT(sizeof(Handle) == sizeof(MojoHandle),
 189                     bad_size_for_cpp_Handle);
 190
 191 // The scoper should also impose no more overhead.
 192 typedef ScopedHandleBase<Handle> ScopedHandle;
 193 MOJO_COMPILE_ASSERT(sizeof(ScopedHandle) == sizeof(Handle),
 194                     bad_size_for_cpp_ScopedHandle);
 195
 196 inline MojoResult Wait(const Handle& handle,
 197                        MojoHandleSignals signals,
 198                        MojoDeadline deadline) {
 199   return MojoWait(handle.value(), signals, deadline);
 200 }
 201
 202 // |HandleVectorType| and |FlagsVectorType| should be similar enough to
 203 // |std::vector<Handle>| and |std::vector<MojoHandleSignals>|, respectively:
 204 //  - They should have a (const) |size()| method that returns an unsigned type.
 205 //  - They must provide contiguous storage, with access via (const) reference to
 206 //    that storage provided by a (const) |operator[]()| (by reference).
 207 template <class HandleVectorType, class FlagsVectorType>
 208 inline MojoResult WaitMany(const HandleVectorType& handles,
 209                            const FlagsVectorType& signals,
 210                            MojoDeadline deadline) {
 211   if (signals.size() != handles.size())
 212     return MOJO_RESULT_INVALID_ARGUMENT;
 213   if (handles.size() > std::numeric_limits<uint32_t>::max())
 214     return MOJO_RESULT_OUT_OF_RANGE;
 215
 216   if (handles.size() == 0)
 217     return MojoWaitMany(NULL, NULL, 0, deadline);
 218
 219   const Handle& first_handle = handles[0];
 220   const MojoHandleSignals& first_signals = signals[0];
 221   return MojoWaitMany(
 222       reinterpret_cast<const MojoHandle*>(&first_handle),
 223       reinterpret_cast<const MojoHandleSignals*>(&first_signals),
 224       static_cast<uint32_t>(handles.size()),
 225       deadline);
 226 }
 227
 228 // |Close()| takes ownership of the handle, since it'll invalidate it.
 229 // Note: There's nothing to do, since the argument will be destroyed when it
 230 // goes out of scope.
 231 template <class HandleType>
 232 inline void Close(ScopedHandleBase<HandleType> /*handle*/) {}
 233
 234 // Most users should typically use |Close()| (above) instead.
 235 inline MojoResult CloseRaw(Handle handle) {
 236   return MojoClose(handle.value());
 237 }
 238
 239 // Strict weak ordering, so that |Handle|s can be used as keys in |std::map|s,
 240 // etc.
 241 inline bool operator<(const Handle& a, const Handle& b) {
 242   return a.value() < b.value();
 243 }
 244
 245 }  // namespace mojo
 246
 247 #endif  // MOJO_PUBLIC_CPP_SYSTEM_HANDLE_H_