Repository: mesos Updated Branches: refs/heads/master 799e2f9e8 -> 89594b5eb
Improvements to libprocess/README.md. Review: https://reviews.apache.org/r/35363 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/89594b5e Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/89594b5e Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/89594b5e Branch: refs/heads/master Commit: 89594b5eb5c480da0ea77f48b6fa2b556ae687c0 Parents: 799e2f9 Author: Joerg Schad <[email protected]> Authored: Tue Jun 23 11:35:46 2015 +0200 Committer: Bernd Mathiske <[email protected]> Committed: Tue Jun 23 11:38:35 2015 +0200 ---------------------------------------------------------------------- 3rdparty/libprocess/README.md | 147 ++++++++++++++++--------------------- 1 file changed, 64 insertions(+), 83 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/89594b5e/3rdparty/libprocess/README.md ---------------------------------------------------------------------- diff --git a/3rdparty/libprocess/README.md b/3rdparty/libprocess/README.md index 4dcd150..f7a6aeb 100644 --- a/3rdparty/libprocess/README.md +++ b/3rdparty/libprocess/README.md @@ -16,100 +16,77 @@ 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. - -Processes assume they have callers/clients and thus should avoid -blocking at all costs. +in a serial fashion. To always be responsive processes should avoid blocking at all costs. A process can be identified symbolically by its [PID](#pid). -Functional composition of different processes enabled by the concept -of a [Future](#future) and a [Promise](#promise). A `Future` is a -read-only placeholder for a result which might be computed -asynchronously, while the Promise on the other side is the writable -placeholder to fullfill the corresponding `Future`. Continutation -allow chaining of futures. - -Local messaging between different processes is enabled via the -following concepts: [delay](#delay), [defer](#defer), and -[dispatch](#dispatch). Remote messaging is done via [send](#send), +Basic communication between processes is supported by [send](#send), [route](#route), and [install](#install). -Usually the above mention concepts are applied in comination in -certain pattern. See the [Table of Patterns](#table_pattern) for -details. - -<!--- -# Subprocess - -Resource handling: #owned #shared - -Networking: #Network, HTTP, Socket, help - -testing: check gmock gtest - -Logging, Monitoring, Statistics: #Logging, #Profiler, #System, #Statistics, #Timeseries, #Metrics +At a higher level, functional composition of interactions between processes is facilitated by the concept +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). -Time Concepts: #Clock, #Event, #Filter, #Time, #Timer, #Timeout, #RateLimiter +This is one of the major [patterns](#table_pattern) which combine the [main concepts](#table_concepts) of libprocess. -Cleanup: #Garbarge Collection, #Reaper -> Remove Run.hpp?? ----> ## 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="#id">ID</a> * <a href="#pid">PID</a> * <a href="#process">Process</a> * <a href="#promise">Promise</a> <!--- -* <a href="#gc">Garbage Collection, Reaper</a>2 -* <a href="#dispatch">Dispatch</a>2 -* <a href="#event">Event</a>2 -* <a href="#help">Help</a>3 -* <a href="#http">Network, HTTP, Socket</a>3 -* <a href="#id">ID</a>?3 -* <a href="#io">IO</a>3 -* <a href="#latch">Latch, Mutex</a>3 -* <a href="#limiter">Limiter </a>3 -* <a href="#logging">Logging</a>2 -* <a href="#clock">Clock, Time, Timeout</a>2 -* <a href="#gc">Garbage Collection, Reaper</a>2 -* <a href="#process">Process, Executor, Once</a>2 - -* <a href="#profiler">Profiler</a>3 -* <a href="#queue">Queue</a>3 -* <a href="#statistics">Statistics, Timeseries</a>3 -* * <a href="#adress">Adress</a> -* <a href="#async">Async</a> +* <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="#clockPattern">Timer Pattern</a> -* <a href="#clockPattern">Reaper Pattern</a> +* <a href="#timerPattern">Timer Pattern</a> +* <a href="#reaperPattern">Reaper Pattern</a> ## 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` -Defers a `dispatch` on some process (i.e., a deferred asynchronous -function/method invocation). +Defer creates a deferred [dispatch](#dispatch). +<!--- ~~~{.cpp} using namespace process; @@ -128,25 +105,21 @@ private: Queue<int> queue; }; ~~~ +---> -`defer` returns a new type (`Deferred<Return(Args)>`) that acts like a -standard function, and an API can force asynchronous callback -semantics by requiring that type. <a name="delay"/> ## `delay` +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` performs asynchronous function (method) invocation (think -Erlangs `gen_server cast`, but no `call` analogue). - - +<!--- ~~~{.cpp} using namespace process; @@ -172,18 +145,20 @@ 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. + +Futures can be created in numerous ways: awaiting the result of a method call with [defer](#defer), [dispatch](#dispatch), and [delay](#delay) or as the read-end of a [promise](#promise). -The counterpart on the producer side is a [Promise](#promise). <a name="id"/> -## ID +## `ID` Generates a unique identifier string given a prefix. This is used to provide `PID` names. @@ -192,10 +167,11 @@ 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). +<!--- ~~~{.cpp} using namespace process; @@ -214,7 +190,7 @@ int main(int argc, char** argv) return 0; } ~~~ - +---> <a name="process"/> ## `Process` @@ -230,6 +206,7 @@ time. Processes provide execution contexts (only one thread executing within a process at a time so no need for per process synchronization). +<!--- ~~~{.cpp} using namespace process; @@ -244,13 +221,14 @@ 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. +<!--- ~~~{.cpp} using namespace process; @@ -286,11 +264,14 @@ int main(int argc, char** argv) ...; } ~~~ - +---> <a name="route"/> ## `route` +Route installs an http endpoint onto a process. + +<!--- ~~~{.cpp} using namespace process; using namespace process::http; @@ -312,10 +293,11 @@ 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; @@ -336,7 +318,7 @@ int main(int argc, char** argv) } ~~~ -When future is completed, callbacks get invoked. + <!--- Explain: @@ -349,13 +331,12 @@ Explain: ## Pattern/Examples -... - - -## Building +<a name="futureChaining" /> +<a name="clockPattern" /> +<a name="timerPattern" /> +<a name="reaperPattern" /> -... +## Building Libprocess -### Dependencies -> NOTE: Libprocess requires the following third party libraries: ... +## Dependencies
