Tool API: Component Providers, Join Points, and State Extensions

rDSN is designed to be customizable and extensible to satisfy the following needs.

• Fit rDSN based applications into existing cluster operation systems, by adopting their performance counters, logging libraries, etc.
• Adopt libraries with even higher performance, e.g., RDMA-based network libraries, specially optimized locks, task queues, etc.
• Developers' personal favor of certain libraries.
• Requirements from specific tools, e.g., a simulator virtualizes time and network by replacing these two components; a tracer attaches timestamps to tasks and RPC messages to calculate the time cost for each stage of an execution flow.

rDSN's Tool API therefore provides three mechanisms to achieve these goals. Tool examples can be found here.

Component Providers

rDSN defines the interface of certain components (e.g., lock), and people can always implement their own and register it into the framework. Meanwhile, because there will be multiple implementations for the same interfaces, it also helps debugging (either correctness or performance) by comparing the system with different component implementations. Currently, rDSN supports the following components to be registered (always check the tool API header file for the latest list), and you can always find their example implementations in the source tree as references.

Task Execution

• [task queue] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/task_queue.h)
• [task worker] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/task_worker.h)
• [admission controller] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/admission_controller.h)

Task Synchronization

• [exclusive lock] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/zlock_provider.h)
• [read-write lock] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/zlock_provider.h)
• [semaphore] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/zlock_provider.h)

RPC and Network

• [network] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/network.h)
• [RPC client session] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/network.h)
• [RPC server session] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/network.h)
• [network file system] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/nfs.h)
• [network message header read & write] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/message_parser.h)

Asynchronous File IO

• [aio provider] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/aio_provider.h)

Environment (Time & Random)

• [env provider] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/env_provider.h)

Other Utilities

• [performance counter] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/perf_counter.h)
• [logging provider] (https://github.com/Microsoft/rDSN/blob/master/include/dsn/internal/logging_provider.h)

Join Points

Join points provide opportunities to monitor and/or manipulate the execution flow as well as its context. See the tracer and fault-injector for examples.

State Extensions

State extension allows tools to attach certain context to the tasks and messages for certain purpose. E.g., the profiler tool attaches timestamp to calculate the time spent on each stage of a RPC call.