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
