From 7a6b0c18903ac44371d18f9c88c29536f8c9945f Mon Sep 17 00:00:00 2001 From: "viettrungluu@chromium.org" Date: Tue, 22 Apr 2014 04:55:47 +0000 Subject: Mojo: Update/add README.md files. Also move async_waiter.h from c/system to c/environment. (It's not a part of the system API per se; instead, it defines stuff that the app must provide to, e.g., the gles2 subsystem. This move makes the organization of the C subdirectory more closely parallel the C++ subdirectory.) R=darin@chromium.org Review URL: https://codereview.chromium.org/244883005 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@265176 0039d316-1c4b-4281-b951-d872f2087c98 --- mojo/bindings/js/waiting_callback.h | 2 +- mojo/environment/default_async_waiter_impl.h | 2 +- mojo/mojo_public.gypi | 1 - mojo/public/README.md | 75 ++++++++-------------- mojo/public/c/README.md | 45 +++++++++++++ mojo/public/c/environment/async_waiter.h | 40 ++++++++++++ mojo/public/c/gles2/DEPS | 3 + mojo/public/c/gles2/gles2.h | 2 +- mojo/public/c/system/async_waiter.h | 40 ------------ mojo/public/c/system/tests/core_unittest_pure_c.c | 2 +- mojo/public/cpp/README.md | 71 ++++++++++++++++++++ mojo/public/cpp/environment/DEPS | 3 + mojo/public/cpp/environment/default_async_waiter.h | 2 +- mojo/public/gles2/gles2_private.h | 2 +- 14 files changed, 196 insertions(+), 94 deletions(-) create mode 100644 mojo/public/c/README.md create mode 100644 mojo/public/c/environment/async_waiter.h create mode 100644 mojo/public/c/gles2/DEPS delete mode 100644 mojo/public/c/system/async_waiter.h create mode 100644 mojo/public/cpp/README.md create mode 100644 mojo/public/cpp/environment/DEPS diff --git a/mojo/bindings/js/waiting_callback.h b/mojo/bindings/js/waiting_callback.h index bc17d19..90cf284 100644 --- a/mojo/bindings/js/waiting_callback.h +++ b/mojo/bindings/js/waiting_callback.h @@ -8,7 +8,7 @@ #include "gin/handle.h" #include "gin/runner.h" #include "gin/wrappable.h" -#include "mojo/public/c/system/async_waiter.h" +#include "mojo/public/c/environment/async_waiter.h" namespace mojo { namespace js { diff --git a/mojo/environment/default_async_waiter_impl.h b/mojo/environment/default_async_waiter_impl.h index 266a70f6..8e697cb 100644 --- a/mojo/environment/default_async_waiter_impl.h +++ b/mojo/environment/default_async_waiter_impl.h @@ -6,7 +6,7 @@ #define MOJO_ENVIRONMENT_DEFAULT_ASYNC_WAITER_IMPL_H_ #include "mojo/environment/mojo_environment_impl_export.h" -#include "mojo/public/c/system/async_waiter.h" +#include "mojo/public/c/environment/async_waiter.h" namespace mojo { namespace internal { diff --git a/mojo/mojo_public.gypi b/mojo/mojo_public.gypi index 9defef5..b4b1942 100644 --- a/mojo/mojo_public.gypi +++ b/mojo/mojo_public.gypi @@ -26,7 +26,6 @@ ], }, 'sources': [ - 'public/c/system/async_waiter.h', 'public/c/system/core.h', 'public/c/system/macros.h', 'public/c/system/system_export.h', diff --git a/mojo/public/README.md b/mojo/public/README.md index 32fc4b1..a31a8a8 100644 --- a/mojo/public/README.md +++ b/mojo/public/README.md @@ -1,62 +1,43 @@ Mojo Public API =============== -The Mojo Public API is a binary stable API to the Mojo system. There are -several components to the API: +The Mojo Public API is a binary stable API to the Mojo system. -Bindings --------- - -This directory contains a static library that clients may link into their -binary. The contents of this directory are not binary stable as each client is -free to use whichever version they prefer. +It consists of support for a number of programming languages (with a directory +for each support language), some "build" tools and build-time requirements, and +interface definitions for Mojo services (specified using an IDL). -This directory also contains a compiler that translates mojom interface -definition files into idiomatic bindings for various languages, including -C++ and JavaScript. Clients are expected to statically link with the generated -code, which reads and writes the binary stable IPC message format. +Note that there are various subdirectories named tests/. These contain tests of +the code in the enclosing directory, and are not meant for use by Mojo +applications. -Environment ------------ +C/CPP/JS +-------- -This directory contains a static library that clients may link into their -binary. The contents of this directory are not binary stable as each client is -free to use whichever version they prefer. +The c/, cpp/, js/ subdirectories define the API for C, C++, and JavaScript, +respectively. -The environment static library represents the shared state that is needed to -support the Bindings and GLES2 libraries. It depends on the Utility library. +The basic principle for these directories is that they consist of the source +files that one needs at build/deployment/run time (as appropriate for the +language), organized in a natural way for the particular language. -GLES2 ------ +Interfaces +---------- -The IPC protocol used to communicate between Mojo client and the GLES2 -service is not binary stable. To insulate themselves from changes in this -protocol, clients are expected to link dynamically against the standard GLES2 -headers from Khronos and the headers in this directory, which provide an -adaptor between the GLES2 C API and the underlying IPC protocol. +The interfaces/ subdirectory contains Mojo IDL (a.k.a. .mojom) descriptions of +standard Mojo services. -System ------- +Platform +-------- -This directory defines the interface between Mojo clients and the Mojo IPC -system. Although the Mojo IPC message format is binary stable, the mechanism -by which these messages are transported is not stable. To insulate themselves -from changes in the underlying transport, clients are expected to link against -these headers dynamically. +The platform/ subdirectory contains any build-time requirements (e.g., static +libraries) that may be needed to produce a Mojo application for certain +platforms, such as a native shared library or as a NaCl binary. -Tests +Tools ----- -This directory contains tests for code contained in the public API. Mojo -clients are expected to ignore this directory. - -Utility -------- - -This directory contains a static library that clients may link into their -binary. The contents of this directory are not binary stable as each client is -free to use whichever version they prefer. - -The Utility static library most notably defines an implementation of a RunLoop -based on the MojoWaitMany that clients may use as the basis for asynchronous -message processing. +The tools/ subdirectory contains tools that are useful/necessary at +build/deployment time. These tools may be needed (as a practical necessity) to +use the API in any given language, e.g., to generate bindings from Mojo IDL +files. diff --git a/mojo/public/c/README.md b/mojo/public/c/README.md new file mode 100644 index 0000000..8e11545 --- /dev/null +++ b/mojo/public/c/README.md @@ -0,0 +1,45 @@ +Mojo Public C API +================= + +This directory contains C language bindings for the Mojo Public API. + +Environment +----------- + +The environment/ subdirectory defines some common things that, while not part of +the system API, may be required for GLES2 (for example). These are things that a +Mojo application may be required to provide to the GLES2 (for example) library +in order to use it. (However, the Mojo application may implement these things as +it sees fit.) + +GLES2 +----- + +The gles2/ subdirectory defines the GLES2 C API that's available to Mojo +applications. To use GLES2, Mojo applications must link against a dynamic +library (the exact mechanism being platform-dependent) and use the header files +in this directory as well as the standard Khronos GLES2 header files. + +The reason for this, rather than providing GLES2 using the standard Mojo IPC +mechanism, is performance: The protocol (and transport mechanisms) used to +communicate with the Mojo GLES2 service is not stable nor "public" (mainly for +performance reasons), and using the dynamic library shields the application from +changes to the underlying system. + +System +------ + +The system/ subdirectory provides definitions of the basic low-level API used by +all Mojo applications (whether directly or indirectly). These consist primarily +of the IPC primitives used to communicate with Mojo services. + +Though the message protocol is stable, the implementation of the transport is +not, and access to the IPC mechanisms must be via the primitives defined in this +directory. + +Test Support +------------ + +This directory contains a C API for running tests. This API is only available +under special, specific test conditions. It is not meant for general use by Mojo +applications. diff --git a/mojo/public/c/environment/async_waiter.h b/mojo/public/c/environment/async_waiter.h new file mode 100644 index 0000000..0568954 --- /dev/null +++ b/mojo/public/c/environment/async_waiter.h @@ -0,0 +1,40 @@ +// 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_C_ENVIRONMENT_ASYNC_WAITER_H_ +#define MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ + +#include "mojo/public/c/system/core.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef uintptr_t MojoAsyncWaitID; + +typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result); + +struct MojoAsyncWaiter { + // Asynchronously call MojoWait on a background thread, and pass the result + // of MojoWait to the given MojoAsyncWaitCallback on the current thread. + // Returns a non-zero MojoAsyncWaitID that can be used with CancelWait to + // stop waiting. This identifier becomes invalid once the callback runs. + MojoAsyncWaitID (*AsyncWait)(struct MojoAsyncWaiter* waiter, + MojoHandle handle, + MojoWaitFlags flags, + MojoDeadline deadline, + MojoAsyncWaitCallback callback, + void* closure); + + // Cancel an existing call to AsyncWait with the given MojoAsyncWaitID. The + // corresponding MojoAsyncWaitCallback will not be called in this case. + void (*CancelWait)(struct MojoAsyncWaiter* waiter, + MojoAsyncWaitID wait_id); +}; + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ diff --git a/mojo/public/c/gles2/DEPS b/mojo/public/c/gles2/DEPS new file mode 100644 index 0000000..3887457 --- /dev/null +++ b/mojo/public/c/gles2/DEPS @@ -0,0 +1,3 @@ +include_rules = [ + "+mojo/public/c/environment", +] diff --git a/mojo/public/c/gles2/gles2.h b/mojo/public/c/gles2/gles2.h index 6b20b9c..3ee249d 100644 --- a/mojo/public/c/gles2/gles2.h +++ b/mojo/public/c/gles2/gles2.h @@ -10,9 +10,9 @@ #include #include +#include "mojo/public/c/environment/async_waiter.h" #include "mojo/public/c/gles2/gles2_export.h" #include "mojo/public/c/gles2/gles2_types.h" -#include "mojo/public/c/system/async_waiter.h" #include "mojo/public/c/system/core.h" #ifdef __cplusplus diff --git a/mojo/public/c/system/async_waiter.h b/mojo/public/c/system/async_waiter.h deleted file mode 100644 index ab999a3..0000000 --- a/mojo/public/c/system/async_waiter.h +++ /dev/null @@ -1,40 +0,0 @@ -// 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_C_SYSTEM_ASYNC_WAITER_H_ -#define MOJO_PUBLIC_C_SYSTEM_ASYNC_WAITER_H_ - -#include "mojo/public/c/system/core.h" - -#ifdef __cplusplus -extern "C" { -#endif - -typedef uintptr_t MojoAsyncWaitID; - -typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result); - -struct MojoAsyncWaiter { - // Asynchronously call MojoWait on a background thread, and pass the result - // of MojoWait to the given MojoAsyncWaitCallback on the current thread. - // Returns a non-zero MojoAsyncWaitID that can be used with CancelWait to - // stop waiting. This identifier becomes invalid once the callback runs. - MojoAsyncWaitID (*AsyncWait)(struct MojoAsyncWaiter* waiter, - MojoHandle handle, - MojoWaitFlags flags, - MojoDeadline deadline, - MojoAsyncWaitCallback callback, - void* closure); - - // Cancel an existing call to AsyncWait with the given MojoAsyncWaitID. The - // corresponding MojoAsyncWaitCallback will not be called in this case. - void (*CancelWait)(struct MojoAsyncWaiter* waiter, - MojoAsyncWaitID wait_id); -}; - -#ifdef __cplusplus -} // extern "C" -#endif - -#endif // MOJO_PUBLIC_C_SYSTEM_ASYNC_WAITER_H_ diff --git a/mojo/public/c/system/tests/core_unittest_pure_c.c b/mojo/public/c/system/tests/core_unittest_pure_c.c index 7293ff2..a95af50 100644 --- a/mojo/public/c/system/tests/core_unittest_pure_c.c +++ b/mojo/public/c/system/tests/core_unittest_pure_c.c @@ -11,8 +11,8 @@ // Include all the header files that are meant to be compilable as C. Start with // core.h, since it's the most important one. +#include "mojo/public/c/environment/async_waiter.h" #include "mojo/public/c/system/core.h" -#include "mojo/public/c/system/async_waiter.h" #include "mojo/public/c/system/macros.h" // The joys of the C preprocessor.... diff --git a/mojo/public/cpp/README.md b/mojo/public/cpp/README.md new file mode 100644 index 0000000..8f03d98 --- /dev/null +++ b/mojo/public/cpp/README.md @@ -0,0 +1,71 @@ +Mojo Public C++ API +=================== + +This directory contains C++ language bindings for the Mojo Public API. + +A number of subdirectories provide wrappers for the lower-level C APIs (in +subdirectories of the same name, under mojo/public/c/). Typically, these +wrappers provide increased convenience and/or type-safety. + +Other subdirectories provide support (static) libraries of various sorts. In +this case, the organization is to have the public interface for the library in +defined in header files in the subdirectory itself and the implementation of the +library at a lower level, under a lib (sub)subdirectory. A developer should be +able to substitute their own implementation of any such support library, and +expect other support libraries, which may depend on that library, to work +properly. + +Bindings +-------- + +The bindings/ subdirectory contains a support (static) library needed by the +code generated by the bindings generator tool (in mojo/public/tools/bindings/), +which translates Mojo IDL (.mojom) files into idiomatic C++ (among other +languages). + +This library depends on the Environment library. + +Environment +----------- + +The environment/ subdirectory contains a support (static) library that +represents shared state needed to support the Bindings and GLES2 libraries. + +This library depends on the Utility library. + + +GLES2 +----- + +The gles2/ subdirectory contains C++ wrappers (and some additional helpers) of +the API defined in mojo/public/c/gles2/ (which provides access to GLES2). + +These wrappers depend on the Environment library. + +Shell +----- + +The shell/ subdirectory contains a support (static) library that aids in writing +Mojo applications and interacting with the Shell service. + +System +------ + +The system/ subdirectory contains C++ wrappers (and some additional helpers) of +the API defined in mojo/public/c/system/, which defines the basic, "core" API, +especially used to communicate with Mojo services. + +Test Support +------------ + +The test_support/ subdirectory contains C++ wrappers of the test-only API +defined in mojo/public/c/test_support/. It is not meant for general use by Mojo +applications. + +Utility +------- + +The utility/ subdirectory contains a support (static) library that provides +various basic functionality. Most notably, it provides an implementation of a +RunLoop based on MojoWaitMany() that applications may use as the basis for +asynchronous message processing. diff --git a/mojo/public/cpp/environment/DEPS b/mojo/public/cpp/environment/DEPS new file mode 100644 index 0000000..3887457 --- /dev/null +++ b/mojo/public/cpp/environment/DEPS @@ -0,0 +1,3 @@ +include_rules = [ + "+mojo/public/c/environment", +] diff --git a/mojo/public/cpp/environment/default_async_waiter.h b/mojo/public/cpp/environment/default_async_waiter.h index d7f48bf..6edfaaa 100644 --- a/mojo/public/cpp/environment/default_async_waiter.h +++ b/mojo/public/cpp/environment/default_async_waiter.h @@ -5,7 +5,7 @@ #ifndef MOJO_PUBLIC_CPP_ENVIRONMENT_DEFAULT_ASYNC_WAITER_H_ #define MOJO_PUBLIC_CPP_ENVIRONMENT_DEFAULT_ASYNC_WAITER_H_ -#include "mojo/public/c/system/async_waiter.h" +#include "mojo/public/c/environment/async_waiter.h" namespace mojo { diff --git a/mojo/public/gles2/gles2_private.h b/mojo/public/gles2/gles2_private.h index 591e043..c92f555 100644 --- a/mojo/public/gles2/gles2_private.h +++ b/mojo/public/gles2/gles2_private.h @@ -7,9 +7,9 @@ #include +#include "mojo/public/c/environment/async_waiter.h" #include "mojo/public/c/gles2/gles2_export.h" #include "mojo/public/c/gles2/gles2_types.h" -#include "mojo/public/c/system/async_waiter.h" #include "mojo/public/cpp/system/core.h" namespace mojo { -- cgit v1.1