README.md
1 How to use this library
2 -----------------------
3 There are three options to use this library:
4
5 ## Option 1) Fully in-process
6 In this mode Producer, Consumers and the Service are hosted in the same process.
7 This is not too interesting other than tests and particular cases of nesting
8 tracing instances coming from different libraries within the same process
9 (concrete example v8, skia and webrtc in Chrome).
10 In this configuration, the client is expected to at least:
11 - Create an Service instance via Service::CreateInstance (see `core/service.h`)
12 - Subclass Producer (`core/producer.h`) and connect it to the service.
13 - Provide a TaskRunner implementation (see `test/test_task_runner.h`)
14 - Provide a trivial SharedMemory implementation (`core/shared_memory.h`) which
15 is simply backed by a malloc() buffer.
16
17 ## Option 2) Using the provided UNIX RPC transport
18 The `include/unix_rpc` provides the building blocks necessary to implement a RPC
19 mechanism that allows Producer(s), Consumer(s) and Service to be hosted on
20 different processes on the same machine and talk over a UNIX domain socket.
21 - Producer(s) are expected to get a service proxy via
22 `UnixServiceConnection::ConnectAsProducer()`.
23 - The `Service` must be instantiated via `UnixServiceHost::CreateInstance()`. The
24 returned instance encapsulates the `Service` and exposes two UNIX sockets (one
25 for Producer(s), one for Consumer(s)) on the current process.
26
27 ## Option 3) Providing a custom RPC transport
28 Similar to Option 2, but the client creates its own transport mechanism,
29 defining how methods are proxies between instances and providing a SharedMemory
30 implementation that can be transferred through RPC. Concrete example of this is
31 Chrome implementing this library over a Mojo transport.
32
33
34 Directory layout
35 ----------------
36
37 `include/`
38 Is the public API that clients of this library are allowed to depend on.
39 Headers inside include/ cannot depend on anything else.
40
41 `src/`
42 Is the actual implementation that clients can link but not expected to access
43 at a source-code level.
44
45
46 **Both have the following sub-structure**:
47
48 `{include,src}/core/`
49 "Core" is the pure c++11 tracing machinery that deals with bookkeeping,
50 ring-buffering, partitioning and multiplexing but knows nothing about
51 platform-specific things like implementation of shared memory and RPC mechanism.
52
53 `{include,src}/unix_rpc/`
54 A concrete implementation of the transport layer based on unix domain sockets
55 and posix shared memory.
56