diff --git a/docs/Advanced.md b/docs/Advanced.md index 7f04f5764..6f1870105 100644 --- a/docs/Advanced.md +++ b/docs/Advanced.md @@ -51,16 +51,17 @@ exit 2 Observables are just wrappers over callback function with ability to be extended via operators. Everytime you apply some operator to observable, observable is copied (or moved). As a result, whole its state is copied/moved too: - be ready for it, so, your callback (or any state inside operators) should be cheap enough to copy -- if you want to avoid it, you can convert your observable to dynamic: it forces to move observable to shared_ptr, as a result, no any future copies/moves +- if you want to avoid it, you can convert your observable to dynamic: it forces to move observable to `shared_ptr`, as a result, no any future copies/moves - some observables/operators have `memory_model` (\ref memory_model) parameter to change strategy of handling your variable: keep to copy/move or move to shared_ptr once Everytime you subscribe subscriber observable just invokes callback for this subscriber and nothing else. It means, that actually observable do nothing and doesn't emit values, **callback emits values**. To achieve better performance use `specific_observable` while it is possible. Same for the argument of callback (for example, when you use `rpp::source::create`): use `const auto&` for subscriber to avoid implicit conversion to dynamic subscriber. +By default, functional programming deals with immutable data and "pure functions". Observable follows this principle, so, it can accept only const functions for callback. ## Observers -By default, functional programming deals with immutable data and "pure functions". Observer follow this principle, so, it can accept only const functions for callbacks. +Observer also follows this principle, so, it can accept only const functions for callbacks. ## Operators diff --git a/docs/Docs.md b/docs/Docs.md index 4186cffb3..0b8ffb552 100644 --- a/docs/Docs.md +++ b/docs/Docs.md @@ -4,4 +4,5 @@ - \subpage advanced - everything about RPP in details - \subpage specific_vs_dynamic - overview of the concept of `specific_` and `dynamic_` types used in **RPP** and how it affects performance - \subpage memory_model - overview of new concept used in RPP related to copy/move/heap usage for objects passed inside RPP +- \subpage exception_guarantee - overview of exception guarantees provided by RPP - \subpage status - current implementation status diff --git a/docs/Exception Guarantee.md b/docs/Exception Guarantee.md new file mode 100644 index 000000000..1c60fb368 --- /dev/null +++ b/docs/Exception Guarantee.md @@ -0,0 +1,7 @@ +# Exception guarantee {#exception_guarantee} + +## Overview + +In non-reactive programming functions/modules throws exception in case of something invalid. As a result, user can catch it and handle it somehow while internal state of objects can be in some state (invalid/untouched/partly valid) and etc. + +In reactive programming there is another way of exception mechanism: throwing exception as is from original place is useless. Notification about "something goes wrong" need to receive observer/subscriber, not owner of callstack. As a result, ANY exception obtained during emitting items and etc WOULD be delivered to subscriber/observer via `on_error` function and then unsubscribe happens. As a result, no any raw exceptions would be throws during using RPP. In case of emitting `on_error` whole internal state of observable keeps valid but it doesn't matter - whole chain would be destroyed due to `on_error` forces unsubscribe. Reactive catching mechanisms like `catch` or `retry` **re-subscribes** on observable. it means, that new chain with new states would be created, not re-used existing one. diff --git a/docs/Quick Start.md b/docs/Quick Start.md index ea18abab7..7bdae110f 100644 --- a/docs/Quick Start.md +++ b/docs/Quick Start.md @@ -6,7 +6,7 @@ For the brief overview of the Reactive pattern read [https://reactivex.io/](http In short, creation of programs with help of ReactivePlusPlus split into several parts: ### 1) Define observables -Observables are sources of your future streams. First of all you need to create some observable which emits values. You can select from some [predefined](https://victimsnino.github.io/ReactivePlusPlus/docs/html/group__observables.html) or built your own. +Observables are sources of your future streams. First of all you need to create some observable which emits values. You can select from some [predefined](https://victimsnino.github.io/ReactivePlusPlus/docs/html/group__creational__operators.html) or built your own. For example, ```cpp @@ -14,7 +14,7 @@ rpp::source::from_callable(&::getchar) ``` observable which emits one char from `cin` via invoking of provided function once after subscription -Action inside observable happens ONLY after subscription on this observable and ONLY for provided subscriber/observer. It means, that you can subscribe on the same observable multiple times! +Action inside observable happens ONLY after subscription on this observable and ONLY for provided subscriber/observer. It means, that you can subscribe on the same observable multiple times! But actually each of this subscriber would see its "own" observable - function invoked especially for this one. ### 2) Chain observable @@ -51,9 +51,15 @@ rpp::source::from_callable(&::getchar) .subscribe([](char v) { std::cout << v; }); ``` Subscribe function applies any from: -- (optional) subscription -- (optional) subscription, `on_next` -- (optional) subscription, `on_next`, `on_error` -- (optional) subscription, `on_next`, `on_completed` -- (optional) subscription, `on_next`, `on_error` `on_completed` -- (optional) subscription, observer +- [none] +- subscription +- `on_next` +- subscription, `on_next` +- `on_next`, `on_error` +- subscription, `on_next`, `on_error` +- `on_next`, `on_completed` +- subscription, `on_next`, `on_completed` +- on_next`, `on_error` `on_completed` +- subscription, `on_next`, `on_error` `on_completed` +- observer +- subscription, observer