Repository: mesos Updated Branches: refs/heads/master b6187a3b2 -> ca30a421c
Remove (almost all) html from libprocess Developer Guide. Review: https://reviews.apache.org/r/35568 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/ca30a421 Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/ca30a421 Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/ca30a421 Branch: refs/heads/master Commit: ca30a421ccc4030a1c0cc91127f703f2c316b756 Parents: b6187a3 Author: Joerg Schad <[email protected]> Authored: Wed Jun 24 17:47:30 2015 +0200 Committer: Bernd Mathiske <[email protected]> Committed: Wed Jun 24 17:48:30 2015 +0200 ---------------------------------------------------------------------- 3rdparty/libprocess/README.md | 164 ++++++++++++++----------------------- 1 file changed, 63 insertions(+), 101 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/ca30a421/3rdparty/libprocess/README.md ---------------------------------------------------------------------- diff --git a/3rdparty/libprocess/README.md b/3rdparty/libprocess/README.md index a4c3452..79304af 100644 --- a/3rdparty/libprocess/README.md +++ b/3rdparty/libprocess/README.md @@ -6,7 +6,9 @@ The library _libprocess_ provides high level elements for an actor programming style with asynchronous message-handling and a variety of related basic system primitives. It's API and implementation are written in C++. + ## Introduction + The design of libprocess is inspired by [Erlang](http://erlang.org), a language that implements the [actor model](http://en.wikipedia.org/wiki/Actor_model). @@ -16,7 +18,7 @@ As the name already suggests, one of the libprocess core concepts is a communicate with other processes by sending and receiving [messages](#message). These are serialized into [Protobuf messages](#protobuf) format and stored in the recipient process' message buffer, from where its thread can process them -in a serial fashion. To always be responsive processes should avoid blocking at all costs. +in a serial fashion. In order to always be responsive processes should avoid blocking at all costs. A process can be identified symbolically by its [PID](#pid). @@ -28,63 +30,41 @@ of a [Future](#future) and a [Promise](#promise). A `Future` is a read-only placeholder for a result which might be computed asynchronously. A Promise on the other side is a handle providing write access to a referenced `Future`. -The following primitives compose closures with future results: [delay](#delay), [defer](#defer), and [dispatch](#dispatch). This gives rise to the pattern of [future chaining](#futureChaining). +The following primitives compose closures with future results: [delay](#delay), [defer](#defer), and [dispatch](#dispatch). This gives rise to the pattern of [future chaining](#future-chaining). -This is one of the major [patterns](#table_pattern) which combine the [main concepts](#table_concepts) of libprocess. +This is one of the major [patterns](#table-of-patterns) which combine the [main concepts](#table_of_concepts) of libprocess. ## Overview + ### Table of Concepts -<a name="table_concepts"/> -* <a href="#async">Async</a> -* <a href="#defer">Defer</a> -* <a href="#delay">Delay</a> -* <a href="#dispatch">Dispatch</a> -* <a href="#future">Future</a> -* <a href="#id">ID</a> -* <a href="#pid">PID</a> -* <a href="#process">Process</a> -* <a href="#promise">Promise</a> +* [Async](#async) +* [Defer](#defer) +* [Delay](#delay) +* [Future](#future) +* [ID](#id) +* [PID](#pid) +* [Process](#process) +* [Promise](#promise) -<!--- -* <a href="#gc">Garbage Collection, Reaper</a> -* <a href="#dispatch">Dispatch</a> -* <a href="#event">Event</a> -* <a href="#help">Help</a> -* <a href="#http">Network, HTTP, Socket</a> -* <a href="#io">IO</a> -* <a href="#latch">Latch, Mutex</a> -* <a href="#limiter">Limiter </a> -* <a href="#logging">Logging</a> -* <a href="#clock">Clock, Time, Timeout</a> -* <a href="#gc">Garbage Collection, Reaper</a> -* <a href="#process">Process, Executor, Once</a> - -* <a href="#profiler">Profiler</a> -* <a href="#queue">Queue</a> -* <a href="#statistics">Statistics, Timeseries</a> -* <a href="#adress">Adress</a> ----> - -<a name="table_pattern"/> ### Table of Patterns -* <a href="#futureChaining">Future Chaining</a> -* <a href="#clockPattern">Clock Pattern</a> -* <a href="#timerPattern">Timer Pattern</a> -* <a href="#reaperPattern">Reaper Pattern</a> + +* [Future Chaining](#future-chaining) +* [Clock Test Pattern](#clock-test-pattern) + ## Concepts -<a name="async"/> ## `async` + Async defines a function template for asynchronously executing function closures. It provides their results as [Futures](#future). -<a name="defer"/> + ## `defer` -Defer creates a deferred [dispatch](#dispatch). +`defer` allows the caller to postpone the decision wether to [dispatch](#dispatch) something by creating a callable object which can perform the dispatch at a later point in time. <!--- ~~~{.cpp} @@ -105,19 +85,17 @@ private: Queue<int> queue; }; ~~~ ----> +----> - -<a name="delay"/> ## `delay` -Delay instead of [dispatching](#dispatch) for execution right away, it allows it to be scheduled after a certain time duration. +`delay` instead of [dispatching](#dispatch) for execution right away, it allows it to be scheduled after a certain time duration. -<a name="dispatch"/> ## `dispatch` -Dispatch schedules a method for asynchronous execution. + +`dispatch` schedules a method for asynchronous execution. <!--- ~~~{.cpp} @@ -145,10 +123,9 @@ int main(int argc, char** argv) ...; } ~~~ ----> +----> -<a name="future"/> ## `Future` The libprocess futures mimic futures in other languages like Scala. It is a placeholder for a future value which is not (necessarily) ready yet. A future in libprocess is a C++ template which is specialized for the return type, for example Try. A future can either be: ready (carrying along a value which can be extracted with .get()), failed (in which case .error() will encode the reason for the failure) or discarded. @@ -157,17 +134,38 @@ Futures can be created in numerous ways: awaiting the result of a method call wi -<a name="id"/> +### `Future::then` + +`Future::then` allows to invoke callbacks once a future is completed. + +~~~{.cpp} +using namespace process; + +int main(int argc, char** argv) +{ + ...; + + Future<int> i = dispatch(process, &QueueProcess<int>::dequeue); + + dispatch(process, &QueueProcess<int>::enqueue, 42); + + i.then([] (int i) { + // Use 'i'. + }); + + ...; +} +~~~ + ## `ID` Generates a unique identifier string given a prefix. This is used to provide `PID` names. -<a name="pid"/> ## `PID` -A PID provides a level of indirection for naming a process without +A `PID` provides a level of indirection for naming a process without having an actual reference (pointer) to it (necessary for remote processes). @@ -190,12 +188,12 @@ int main(int argc, char** argv) return 0; } ~~~ ----> +----> + -<a name="process"/> ## `Process` -A process is an actor, effectively a cross between a thread and an object. +A `process` is an actor, effectively a cross between a thread and an object. Creating/spawning a process is very cheap (no actual thread gets created, and no thread stack gets allocated). @@ -221,12 +219,12 @@ int main(int argc, char** argv) return 0; } ~~~ ----> +----> + -<a name="promise"/> ## `Promise` -A promise is an object that can fulfill a [futures](#future), i.e. assign a result value to it. +A `promise` is an object that can fulfill a [futures](#future), i.e. assign a result value to it. <!--- ~~~{.cpp} @@ -264,12 +262,12 @@ int main(int argc, char** argv) ...; } ~~~ ----> +----> + -<a name="route"/> ## `route` -Route installs an http endpoint onto a process. +`route` installs an http endpoint onto a process. <!--- ~~~{.cpp} @@ -293,50 +291,14 @@ public: // $ curl localhost:1234/queue/enqueue?value=42 ~~~ ----> - -<a name="then"/> -## `Future::then` -Then allows to invoke callbacks once a future is completed. +----> -~~~{.cpp} -using namespace process; - -int main(int argc, char** argv) -{ - ...; - - Future<int> i = dispatch(process, &QueueProcess<int>::dequeue); - - dispatch(process, &QueueProcess<int>::enqueue, 42); - - i.then([] (int i) { - // Use 'i'. - }); - - ...; -} -~~~ - - - -<!--- -Explain: -(1) When should a callback get invoked? -(2) Using what execution context? - Synchronously: using the current thread, blocking whatever was - Asynchronously: using a different thread than the current thread (but what thread?)? ----> ## Pattern/Examples +TODO: ADD PATTERNS -<a name="futureChaining" /> -<a name="clockPattern" /> -<a name="timerPattern" /> -<a name="reaperPattern" /> - -## Building Libprocess +### Future Chaining -## Dependencies +### Clock Test Pattern
