1 Kinetic-C Library Developer Reference
2 =====================================
6 * [Ruby](https://www.ruby-lang.org) (v1.9.3 or higher) scripting language
7 * [RubyGems](http://rubygems.org) (installed w/ `bundle install)
8 * [bundler](http://bundler.io) (v1.3.5 or higher) environment/dependency manager for Ruby projects
9 * Managed gems (installed w/ `bundle install`)
10 * [rake](https://rubygems.org/gems/rake) Make-like build system
11 * [ceedling](https://github.com/ThrowTheSwitch/Ceedling) Build system which extends rake to add support for interaction-based testing
12 * [unity](https://github.com/ThrowTheSwitch/Unity) Unity C test framework (bundled w/ Ceedling)
13 * [cmock](https://github.com/ThrowTheSwitch/CMock) CMock auto mock/fake module generator for C (bundle w/ Ceedling)
14 * [Valgrind](http://valgrind.org/) for validation of memory usage/management
15 * [Doxygen](https://github.com/doxygen)
16 * [GraphViz](http://www.graphviz.org/) used by Doxygen for generating visualizations/graphs
20 [Kinetic-C API Documentation](http://seagate.github.io/kinetic-c/) (generated with Doxygen)
21 * [Kinetic-C API](http://seagate.github.io/kinetic-c/kinetic__client_8h.html)
22 * [Kinetic-C types](http://seagate.github.io/kinetic-c/kinetic__types_8h.html)
23 * [ByteArray API](http://seagate.github.io/kinetic-c/byte__array_8h.html)
24 * The ByteArray and ByteBuffer types are used for exchanging variable length byte-arrays with kinetic-c
25 * e.g. object keys, object value data, etc.
27 There are also some additional [architectural notes](docs) and time-sequence diagrams.
29 [docs]: https://github.com/Seagate/kinetic-c/blob/master/docs/sequence_diagrams/arch_docs.md
31 Common Developer Tasks
32 ----------------------
35 * Start kinteic-java simulator(s)
36 * `make [NUM_SIMS=N] start_sims # defaults to starting 2 simulators, if NUM_SIMS unspecified`
37 * Stop all running kinetic-java simulator(s)
39 * Run all tests and build the library and examples
41 * Run all unit/integration tests
43 * Run all system tests
45 * Run a particular system test
46 * make test_system_<module>
47 * Will expect at least 2 simulators running by default (see above)
48 * Uses the following environment vars, which are loaded dynamically at runtime
49 * `KINTEIC_HOST[1|2]` - Configures the host name/IP for the specified device (default: `localhost`)
50 * `KINTEIC_PORT[1|2]` - Configures the primary port for the specified device (default: `8124`, `8124`)
51 * `KINTEIC_TLS_PORT[1|2]` - Configures the TLS port for the specified device (default: `8443`, `8444`)
52 * Apply license to source files (skips already licensed files)
53 * `make apply_license`
55 Developer Tasks via Rake
56 ------------------------
57 * List rake tasks w/ descriptions
59 * Test a single module (via Ceedling)
60 * `rake test:<module_name>`
61 * Generate API documentation locally
63 * Generate and publish public API documentation
64 * `rake doxygen:update_public_api`
65 * Build/install Google Protocol Buffers support for the Kinetic-Protocol
70 All test sources are located in `test/`, which are additionally broken up into:
71 * `test/unit` - test suites for individual modules
72 * `test/integration` - test suites which integrate multiple modules
73 * `test/system` - system tests whick link against the kinetic-c release library
74 * These tests require at least 2 simulator/drives to run against
76 Adding a new unit/integration test
77 ----------------------------------
78 * Create a file named `test_<name>.c` in either `test/unit` or `test/integration`
79 * These files will automatically be picked up by the Ceedling and added to the regression suite
80 * Build targets for each module will be generated according to what header files are included in the test suite source.
82 * `#include "kinetic_session.h"` will link `kinetic_session.o` into the test target.
83 * `#include "mock_kinetic_session.h"` will create a CMock mock of `kinetic_session.h` and link `mock_kinetic_session.o` into the test target.
84 * `#include <some_lib.h>` will simply include the specified header, assuming it is already available in to the linker.
86 Adding a new system test
87 ------------------------
88 * Create a file named `test_system_<name>.c` in `test/system`
89 * This will create a new system test target invokable via: `make test_system_<name>`
90 * System tests link/run against the full kinetic-c static library.
91 * A generic test fixure is provided and linked into each system test from: `test/support/system_test_fixture.h/c`
92 * See details above for runtime configuration of the system test kinetic devices for running remote simulators or kinetic device hardware.
95 Future development notes
96 ------------------------
98 * epoll(2) could be used internally, in place of poll(2) and multiple
99 listener threads. This only matters in a case where there is a large
100 amount of idle listener connections. When there is a small number of
101 file descriptors, it will add overhead, and epoll is only available
104 * The listener can potentially leak memory on shutdown, in the case
105 where responses have been partially received. This has been a low priority.
107 * There is room for tuning the total number of messages-in-flight
108 in the listener (controlled by `MAX_PENDING_MESSAGES`), how the
109 backpressure is calculated (in `ListenerTask_GetBackpressure`), and the
110 bit shift applied to the backpressure unit (the third argument to
111 `bus_backpressure_delay`, e.g. `LISTENER_BACKPRESSURE_SHIFT`). These
112 derive the feedback that pushes against actions that overload the
113 system. The current setup has worked well with system/integration
114 tests and a stress test program that attempts to overload the message
115 bus over a loopback connection, but other workloads may have different
116 performance trade-offs.