Mojo: Add an "overview" comment to mojo/public/cpp/system/core.h.

mojo/public/cpp/system/core.h

 // Copyright 2013 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_CORE_H_
 #define MOJO_PUBLIC_CPP_SYSTEM_CORE_H_
 
 #include <assert.h>
 #include <stddef.h>
 
 #include <limits>
 
 #include "mojo/public/c/system/core.h"
 #include "mojo/public/c/system/system_export.h"
 #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 (in
+// mojo/public/c/system/core.h -- see that 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 handle.
+//
+// More significantly, |WriteMessageRaw()| exposes the full API complexity of
+// |MojoWriteMessage()| (but doesn't require any extra overhead). It takes a raw
+// array of |Handle|s as input, and takes ownership of them (i.e., invalidates
+// them) on *success* (but not on failure). There are a number of reasons for
+// this. First, C++03 |std::vector|s cannot contain the move-only
+// |Scoped...Handle|s. Second, |std::vector|s impose extra overhead
+// (necessitating heap-allocation of the buffer). Third, |std::vector|s wouldn't
+// provide the desired level of flexibility/safety: a vector of handles would
+// have to be all of the same type (probably |Handle|/|ScopedHandle|). Fourth,
+// it's expected to not be used directly, but instead be used by generated
+// bindings.
+//
+// Other |...Raw()| functions expose similar rough edges, e.g., dealing with raw
+// pointers (and lengths) instead of taking |std::vector|s or similar.
+
 // Standalone functions --------------------------------------------------------
 
 inline MojoTimeTicks GetTimeTicksNow() {
   return MojoGetTimeTicksNow();
 }
 
 // ScopedHandleBase ------------------------------------------------------------
 
 // Scoper for the actual handle types defined further below. It's move-only,
 // like the C++11 |unique_ptr|.
@@ skipping 55 matching lines @@
   return ScopedHandleBase<HandleType>(handle);
 }
 
 // Handle ----------------------------------------------------------------------
 
 const MojoHandle kInvalidHandleValue = MOJO_HANDLE_INVALID;
 
 // Wrapper base class for |MojoHandle|.
 class Handle {
  public:
-  Handle() : value_(MOJO_HANDLE_INVALID) {}
+  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_ != MOJO_HANDLE_INVALID;
+    return value_ != kInvalidHandleValue;
   }
 
   MojoHandle value() const { return value_; }
   MojoHandle* mutable_value() { return &value_; }
   void set_value(MojoHandle value) { value_ = value; }
 
  private:
   MojoHandle value_;
 
   // Copying and assignment allowed.
@@ skipping 342 matching lines @@
       CreateSharedBuffer(&options, num_bytes, &handle);
   assert(result == MOJO_RESULT_OK);
 }
 
 inline SharedBuffer::~SharedBuffer() {
 }
 
 }  // namespace mojo
 
 #endif  // MOJO_PUBLIC_CPP_SYSTEM_CORE_H_