Adding API documentation to the C++ Array and Binding classes. R=yzshen@chromium.org Review URL: https://codereview.chromium.org/792543005
diff --git a/mojo/public/cpp/bindings/array.h b/mojo/public/cpp/bindings/array.h index ca4e9cc..5194663 100644 --- a/mojo/public/cpp/bindings/array.h +++ b/mojo/public/cpp/bindings/array.h
@@ -18,6 +18,8 @@ namespace mojo { +// Represents a moveable array with contents of type |T|. The array can be null, +// meaning that no value has been assigned to it. Null is distinct from empty. template <typename T> class Array { MOJO_MOVE_ONLY_TYPE(Array) @@ -31,30 +33,42 @@ typedef internal::Array_Data<typename internal::WrapperTraits<T>::DataType> Data_; + // Constructs a new array that is null. Array() : is_null_(true) {} + + // Constructs a new non-null array of the specified size. The elements will + // be value-initialized (meaning that they will be initialized by their + // default constructor, if any, or else zero-initialized). explicit Array(size_t size) : vec_(size), is_null_(false) { Traits::Initialize(&vec_); } ~Array() { Traits::Finalize(&vec_); } + // Moves the contents of |other| into this array. Array(Array&& other) : is_null_(true) { Take(&other); } Array& operator=(Array&& other) { Take(&other); return *this; } + // Creates a non-null array of the specified size. The elements will be + // value-initialized (meaning that they will be initialized by their default + // constructor, if any, or else zero-initialized). static Array New(size_t size) { return Array(size).Pass(); } + // Creates a new array with a copy of the contents of |other|. template <typename U> static Array From(const U& other) { return TypeConverter<Array, U>::Convert(other); } + // Copies the contents of this array to a new object of type |U|. template <typename U> U To() const { return TypeConverter<U, Array>::Convert(*this); } + // Resets the contents of this array back to null. void reset() { if (!vec_.empty()) { Traits::Finalize(&vec_); @@ -63,41 +77,65 @@ is_null_ = true; } + // Indicates whether the array is null (which is distinct from empty). bool is_null() const { return is_null_; } + // Returns a reference to the first element of the array. Calling this on a + // null or empty array causes undefined behavior. ConstRefType front() const { return vec_.front(); } RefType front() { return vec_.front(); } + // Returns the size of the array, which will be zero if the array is null. size_t size() const { return vec_.size(); } + // Returns a reference to the element at zero-based |offset|. Calling this on + // an array with size less than |offset|+1 causes undefined behavior. ConstRefType at(size_t offset) const { return Traits::at(&vec_, offset); } ConstRefType operator[](size_t offset) const { return at(offset); } - RefType at(size_t offset) { return Traits::at(&vec_, offset); } RefType operator[](size_t offset) { return at(offset); } + // Pushes |value| onto the back of the array. If this array was null, it will + // become non-null with a size of 1. void push_back(ForwardType value) { is_null_ = false; Traits::PushBack(&vec_, value); } + // Resizes the array to |size| and makes it non-null. Otherwise, works just + // like the resize method of |std::vector|. void resize(size_t size) { is_null_ = false; Traits::Resize(&vec_, size); } + // Returns a const reference to the |std::vector| managed by this class. If + // the array is null, this will be an empty vector. const std::vector<StorageType>& storage() const { return vec_; } operator const std::vector<StorageType>&() const { return vec_; } + // Swaps the contents of this array with the |other| array, including + // nullness. void Swap(Array* other) { std::swap(is_null_, other->is_null_); vec_.swap(other->vec_); } + + // Swaps the contents of this array with the specified vector, making this + // array non-null. Since the vector cannot represent null, it will just be + // made empty if this array is null. void Swap(std::vector<StorageType>* other) { is_null_ = false; vec_.swap(*other); } + // Returns a copy of the array where each value of the new array has been + // "cloned" from the corresponding value of this array. If this array contains + // primitive data types, this is equivalent to simply copying the contents. + // However, if the array contains objects, then each new element is created by + // calling the |Clone| method of the source element, which should make a copy + // of the element. + // // Please note that calling this method will fail compilation if the element // type cannot be cloned (which usually means that it is a Mojo handle type or // a type contains Mojo handles). @@ -108,6 +146,10 @@ return result.Pass(); } + // Indicates whether the contents of this array are equal to |other|. A null + // array is only equal to another null array. Elements are compared using the + // |ValueTraits::Equals| method, which in most cases calls the |Equals| method + // of the element. bool Equals(const Array& other) const { if (is_null() != other.is_null()) return false; @@ -136,6 +178,9 @@ bool is_null_; }; +// A |TypeConverter| that will create an |Array<T>| containing a copy of the +// contents of an |std::vector<E>|, using |TypeConverter<T, E>| to copy each +// element. The returned array will always be non-null. template <typename T, typename E> struct TypeConverter<Array<T>, std::vector<E>> { static Array<T> Convert(const std::vector<E>& input) { @@ -146,6 +191,9 @@ } }; +// A |TypeConverter| that will create an |std::vector<E>| containing a copy of +// the contents of an |Array<T>|, using |TypeConverter<E, T>| to copy each +// element. If the input array is null, the output vector will be empty. template <typename E, typename T> struct TypeConverter<std::vector<E>, Array<T>> { static std::vector<E> Convert(const Array<T>& input) {
diff --git a/mojo/public/cpp/bindings/binding.h b/mojo/public/cpp/bindings/binding.h index 4ecc6a8..658b6a0 100644 --- a/mojo/public/cpp/bindings/binding.h +++ b/mojo/public/cpp/bindings/binding.h
@@ -17,8 +17,10 @@ namespace mojo { -// This binds an interface implementation a pipe. Deleting the binding closes -// the pipe. +// Represents the binding of an interface implementation to a message pipe. +// When the |Binding| object is destroyed, the binding between the message pipe +// and the interface is torn down and the message pipe is closed, leaving the +// interface implementation in an unbound state. // // Example: // @@ -43,13 +45,29 @@ // // delete FooImpl on connection errors. // } // }; +// +// The caller may specify a |MojoAsyncWaiter| to be used by the connection when +// waiting for calls to arrive. Normally it is fine to use the default waiter. +// However, the caller may provide their own implementation if needed. The +// |Binding| will not take ownership of the waiter, and the waiter must outlive +// the |Binding|. +// +// TODO(ggowan): Find out under what circumstances the caller may need to +// provide their own implementation of MojoAsyncWaiter, and then describe those +// circumstances. template <typename Interface> class Binding : public ErrorHandler { public: using Client = typename Interface::Client; + // Constructs an incomplete binding that will use the implementation |impl|. + // The binding may be completed with a subsequent call to the |Bind| method. + // Does not take ownership of |impl|, which must outlive the binding. explicit Binding(Interface* impl) : impl_(impl) { stub_.set_sink(impl_); } + // Constructs a completed binding of message pipe |handle| to implementation + // |impl|. Does not take ownership of |impl|, which must outlive the binding. + // See class comment for definition of |waiter|. Binding(Interface* impl, ScopedMessagePipeHandle handle, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) @@ -57,6 +75,12 @@ Bind(handle.Pass(), waiter); } + // Constructs a completed binding of |impl| to a new message pipe, passing the + // client end to |ptr|, which takes ownership of it. The caller is expected to + // pass |ptr| on to the client of the service. Does not take ownership of any + // of the parameters. |impl| must outlive the binding. |ptr| only needs to + // last until the constructor returns. See class comment for definition of + // |waiter|. Binding(Interface* impl, InterfacePtr<Interface>* ptr, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) @@ -64,6 +88,10 @@ Bind(ptr, waiter); } + // Constructs a completed binding of |impl| to the message pipe endpoint in + // |request|, taking ownership of the endpoint. Does not take ownership of + // |impl|, which must outlive the binding. See class comment for definition of + // |waiter|. Binding(Interface* impl, InterfaceRequest<Interface> request, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) @@ -71,6 +99,8 @@ Bind(request.PassMessagePipe(), waiter); } + // Tears down the binding, closing the message pipe and leaving the interface + // implementation unbound. ~Binding() override { delete proxy_; if (internal_router_) { @@ -79,6 +109,9 @@ } } + // Completes a binding that was constructed with only an interface + // implementation. Takes ownership of |handle| and binds it to the previously + // specified implementation. See class comment for definition of |waiter|. void Bind( ScopedMessagePipeHandle handle, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { @@ -95,6 +128,12 @@ proxy_ = new typename Client::Proxy_(internal_router_); } + // Completes a binding that was constructed with only an interface + // implementation by creating a new message pipe, binding one end of it to the + // previously specified implementation, and passing the other to |ptr|, which + // takes ownership of it. The caller is expected to pass |ptr| on to the + // eventual client of the service. Does not take ownership of |ptr|. See + // class comment for definition of |waiter|. void Bind( InterfacePtr<Interface>* ptr, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { @@ -103,35 +142,50 @@ Bind(pipe.handle1.Pass(), waiter); } + // Completes a binding that was constructed with only an interface + // implementation by removing the message pipe endpoint from |request| and + // binding it to the previously specified implementation. See class comment + // for definition of |waiter|. void Bind( InterfaceRequest<Interface> request, const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { Bind(request.PassMessagePipe(), waiter); } + // Blocks the calling thread until either a call arrives on the previously + // bound message pipe, or an error occurs. bool WaitForIncomingMethodCall() { MOJO_DCHECK(internal_router_); return internal_router_->WaitForIncomingMessage(); } + // Closes the message pipe that was previously bound. void Close() { MOJO_DCHECK(internal_router_); internal_router_->CloseMessagePipe(); } + // Sets an error handler that will be called if a connection error occurs on + // the bound message pipe. void set_error_handler(ErrorHandler* error_handler) { error_handler_ = error_handler; } - // ErrorHandler implementation + // Implements the |Binding|'s response to a connection error. void OnConnectionError() override { if (error_handler_) error_handler_->OnConnectionError(); } + // Returns the interface implementation that was previously specified. Caller + // does not take ownership. Interface* impl() { return impl_; } + + // Returns the client's interface. Client* client() { return proxy_; } + // Indicates whether the binding has been completed (i.e., whether a message + // pipe has been bound to the implementation). bool is_bound() const { return !!internal_router_; } // Exposed for testing, should not generally be used.