Skip to content

Commit 4012288

Browse files
schlangsterschlangster
committed
Updated readme.
1 parent 47ec985 commit 4012288

1 file changed

Lines changed: 37 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 37 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,27 @@
11
# Introduction
2-
Cpp.React is an experimental [Reactive Programming](http://en.wikipedia.org/wiki/Reactive_programming) library for C++11.
2+
Cpp.React is reactive programming library for C++11.
3+
Generally speaking, it provides abstractions to handle change propagation and data processing for a push-based event model.
4+
It is an alternative to implementing imperative change propagation manually through callback functions and side-effects.
35

4-
It provides abstractions to simplify the implementation of reactive behaviour.
6+
The two core features of the library are
57

6-
To react to changing data, reactive variables are declared in terms of functions that calcuate their values, rather than manipulating them directly.
7-
A runtime engine will automatically handle the change propagation by re-calculating data if its dependencies have been modified.
8+
* **signals**, reactive variables that are automatically re-calculated when their dependencies change, and
9+
* **event streams** as composable first class objects.
810

9-
To react to events, event streams are provided as composable first class objects with value semantics.
11+
Signals specifically deal with aspects of time-varying state, whereas event streams facilitate generic processing.
12+
A set of operations and algorithms can be used to combine signals and events.
13+
Together, these abstractions enable intuitive modeling of dataflow systems in a declarative manner.
1014

11-
For seamless integration with existing code, _reactive domains_ encapsulate a reactive sub-system, with an input interface to trigger changes imperatively, and an output interface to apply side effects.
15+
In this case, declarative means that the programer defines how values are calculated through functional composition of other values.
16+
Applying these calcuations is implicitely handled by a so-called propagation engine as changes are propagated through the dataflow graph.
1217

13-
As an alternative to implementing change propagation or callback-based approaches manually, using Cpp.React results in less boilerplate code and better scalability due to the guarentees of avoiding unnecessary recalculations and glitches.
14-
Furthermore, since functional purity is maintained in each reactive domain, the propagation engine can safely support implicit parallelism for the updating process.
15-
Behind the scenes, task-based programming and dynamic chunking based on collected timing data are employed to optimize parallel utilization.
18+
Since the engine has the "whole picture", it can schedule updates efficiently, so that:
19+
20+
* No value is re-calculated or processed unnecessarily;
21+
* intermediate results are cached to avoid redundant calculations;
22+
* no glitches will occur (i.e. no inconsistent sets of input values).
23+
24+
It can even implicitly parallelize calculations, while automatically taking care of potential data-races and effective utilization of available parallel hardware.
1625

1726
# Documentation
1827
The documentation is still incomplete, but it already contains plenty of useful information and examples.
@@ -42,8 +51,6 @@ make
4251
For more details, see [Build instructions](https://github.com/schlangster/cpp.react/wiki/Build-instructions).
4352

4453
### Dependencies
45-
Cpp.React uses several external dependencies, but only one of them is mandatory:
46-
4754
* [Intel TBB 4.2](https://www.threadingbuildingblocks.org/) (required)
4855
* [Google test framework](https://code.google.com/p/googletest/) (optional, to compile the unit tests)
4956
* [Boost 1.55.0 C++ Libraries](http://www.boost.org/) (optional, to include Reactor.h, which requires `boost::coroutine`)
@@ -59,19 +66,26 @@ They can be combined to expressions to create new signals, which are automatical
5966
using namespace std;
6067
using namespace react;
6168

62-
REACTIVE_DOMAIN(D)
69+
// Define a reactive domain that uses single-threaded, sequential updating
70+
REACTIVE_DOMAIN(D, sequential)
71+
72+
// Define aliases for types of the given domain,
73+
// e.g. using VarSignalT<X> = VarSignal<D,X>
6374
USING_REACTIVE_DOMAIN(D)
6475

6576
// Two reactive variables that can be manipulated imperatively
6677
VarSignalT<int> width = MakeVar<D>(1);
6778
VarSignalT<int> height = MakeVar<D>(2);
6879

6980
// A signal that depends on width and height and multiplies their values
70-
SignalT<int> area = MakeSignal(With(width, height),
81+
SignalT<int> area = MakeSignal(
82+
With(width, height),
7183
[] (int w, int h) {
7284
return w * h;
7385
});
74-
86+
```
87+
```
88+
// Signal values can be accessed imperativly at any time, but only VarSignals can be directly manipulated.
7589
cout << "area: " << area.Value() << endl; // => area: 2
7690

7791
// Width changed, so area is re-calculated automatically
@@ -80,22 +94,19 @@ width.Set(10);
8094
cout << "area: " << area.Value() << endl; // => area: 20
8195
```
8296
83-
For expressions that use operators only, `MakeSignal` can be omitted completely:
97+
Overloaded operators for signal types allow to omit `MakeSignal` in this case for a more concise syntax:
8498
```C++
85-
// Lift as reactive expression
99+
// Lift as reactive expression - equivalent to previous example
86100
SignalT<int> area = width * height;
87101
```
88102

89103
## Events and Observers
90104

91-
Event streams represent flows of discrete values.
92-
They are first-class objects and can be merged, filtered, transformed or composed to more complex types:
93-
94105
```C++
95106
using namespace std;
96107
using namespace react;
97108

98-
REACTIVE_DOMAIN(D)
109+
REACTIVE_DOMAIN(D, sequential)
99110
USING_REACTIVE_DOMAIN(D)
100111

101112
// Two event sources
@@ -109,15 +120,14 @@ EventsT<Token> merged = leftClicked | rightClicked;
109120
auto obs = Observe(merged, [] (Token) {
110121
cout << "clicked!" << endl;
111122
});
112-
113-
// ...
114-
123+
```
124+
```
115125
rightClicked.Emit(); // => clicked!
116126
```
117127
118-
## Implicit parallelism
128+
## Parallelism and concurrency
119129
120-
The change propagation is handled implicitly by a _propagation engine_.
130+
The change propagation is handled implicitly by a propagation engine.
121131
Depending on the selected engine, updates can be parallelized:
122132
123133
```C++
@@ -126,7 +136,7 @@ using namespace react;
126136
127137
// Sequential updating
128138
{
129-
REACTIVE_DOMAIN(D, ToposortEngine<sequential>)
139+
REACTIVE_DOMAIN(D, sequential)
130140
131141
auto a = MakeVar<D>(1);
132142
auto b = MakeVar<D>(2);
@@ -139,7 +149,7 @@ using namespace react;
139149
140150
// Parallel updating
141151
{
142-
REACTIVE_DOMAIN(D, ToposortEngine<parallel>)
152+
REACTIVE_DOMAIN(D, parallel)
143153
144154
auto in = MakeVar<D>(0);
145155

0 commit comments

Comments
 (0)