1# wsrep API node application
2
3## Overview
4
5This is a simple application to demonstrate the usage of wsrep API. It
6deliberately does nothing useful in order to present as concentrated and
7concise API usage as possible.
8
9The program is deliberately written in C to demonstrate the naked API usage.
10For C++ example see a much more advanced integration library at
11https://github.com/codership/wsrep-lib
12
13## High level architecture
14
15Process-wise the program consists of an endless main loop that periodically
16samples and prints performance stats and a configurable number of "master" and
17"slave" threads, with master threads loop executing "transactions" and
18replicating resulting "write sets" and slave threads receiving and processing
19the write sets from other nodes.
20
21Object-wise the program is composed of two main objects: `store` and `wsrep`.
22'store' object contains application "state" and generates and commits changes
23to the state. `wsrep` object contains cluster context and provides interface
24to it. Changes generated by `store` are replicated and certified through
25`wsrep` and then committed to `store`.
26
27## Unit descriptions (in alphabetical order)
28
29#### ctx.h
30A small header to declare the application context structure.
31
32#### log.*
33Implements logging functionality for the application AND
34**a logging callback** for the wsrep provider.
35
36#### main.c
37Defines `main()` routine that initializes storage and wsrep provider, starts
38the worker threads and loops in a statistics collection loop. Even though it is
39not designed to return it still shows the deinitialization order.
40
41#### options.*
42Implements reading configuration options from the command line, does not have
43anything related to wsrep API, but shows which additional parameters must be
44configured for the program to make use of wsrep clustering.
45
46#### socket.*
47Network sockets boilerplate code for setting TCP connections between processes
48(for SST). Has nothing wsrep-related and can be ignored.
49
50#### sst.*
51Defines **SST callbacks** for the wsrep provider and shows how to asynchronously
52implement state snapshot transfer (yes, you don't want to spend eternity in
53callbacks).
54
55#### stats.*
56Implements performance stats collecting function for the main loop. While it is
57an absolutely optional provider functionality, still it shows how to use that.
58
59#### store.*
60Defines the `store` object that pretends to store and modify some data in a
61"transactional" manner. It provides the caller that intends to do a change with
62a *change data* and a *key* for replication and certification.
63
64#### trx.*
65Defines routines to process local and replicated transactions.
66
67#### worker.*
68Implements worker thread pool functinality. Worker threads run routines defined
69in 'trx.*'. Also implements **apply callback** for the wsrep provider.
70
71#### wsrep.*
72Maintains wsrep cluster context: provider instance and cluster membership view.
73While there is little use for the latter in this primitive application, still
74it shows **connected and view callbacks** usage. But mostly, for this
75application its purpose is to initialize the provider, connect to the cluster
76and offer access to initialized provider for other parts of the program.
77
78## Example usage
79```
80./node -f /tmp/galera/0 -v /tmp/galera/0/galera/lib/libgalera_smm.so -o 'pc.weight=2;evs.send_window=2;evs.user_send_window=1;gcache.recover=no' -s 8 -m 16
81```
82