You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by be...@apache.org on 2015/06/03 15:43:47 UTC
[4/4] mesos git commit: Initial clean up pass of libprocess README.md.
Initial clean up pass of libprocess README.md.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/929e3554
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/929e3554
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/929e3554
Branch: refs/heads/master
Commit: 929e35548b878b21683283b560ca27229eb82d10
Parents: ddcddfb
Author: Benjamin Hindman <be...@gmail.com>
Authored: Wed Jun 3 06:37:33 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Wed Jun 3 06:42:28 2015 -0700
----------------------------------------------------------------------
3rdparty/libprocess/README.md | 292 ++++++++++++++++++++-----------------
1 file changed, 155 insertions(+), 137 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/929e3554/3rdparty/libprocess/README.md
----------------------------------------------------------------------
diff --git a/3rdparty/libprocess/README.md b/3rdparty/libprocess/README.md
index 288f085..4dcd150 100644
--- a/3rdparty/libprocess/README.md
+++ b/3rdparty/libprocess/README.md
@@ -6,7 +6,7 @@ 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
+## 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).
@@ -18,20 +18,29 @@ 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
+Processes assume they have callers/clients and thus 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 [Futures](#future) and [Promises](#promise)
-A future is a read-only placeholder for a result which might be computed asynchronously, while the [promise](#promise) on the other side is the writable placeholder to fullfill the corresponding future.
-Continutation allow chaining of futures.
+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), [defere](defere), [async](#async), [sequence](#sequence,), and [dispatch](#dispatch).
-Furthermore libprocess allows for remote messaging via [send](#send), [route](#route), and [install](#install).
+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),
+[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.
-Usually the above mention concepts are applied in comination in certain pattern. See the [Table of Patterns](#table_pattern) for details.
<!---
-#Subprocess
+# Subprocess
Resource handling: #owned #shared
@@ -47,8 +56,8 @@ Cleanup: #Garbarge Collection, #Reaper
> Remove Run.hpp??
--->
-##Overview
-###Table of Concepts
+## Overview
+### Table of Concepts
* <a href="#async">Async</a>
* <a href="#defer">Defer</a>
@@ -59,8 +68,6 @@ Cleanup: #Garbarge Collection, #Reaper
* <a href="#pid">PID</a>
* <a href="#process">Process</a>
* <a href="#promise">Promise</a>
-* <a href="#protobuf">Protobuf</a>
-* <a href="#sequence">Sequence</a>
<!---
* <a href="#gc">Garbage Collection, Reaper</a>2
@@ -79,54 +86,72 @@ Cleanup: #Garbarge Collection, #Reaper
* <a href="#profiler">Profiler</a>3
* <a href="#queue">Queue</a>3
-* <a href="#sequence">Sequence</a>3
* <a href="#statistics">Statistics, Timeseries</a>3
* * <a href="#adress">Adress</a>
* <a href="#async">Async</a>
--->
<a name="table_pattern"/>
-###Table of Patterns
+### Table of Patterns
* <a href="#clockPattern">Clock Pattern</a>
* <a href="#clockPattern">Timer Pattern</a>
* <a href="#clockPattern">Reaper Pattern</a>
-##Concepts
+## Concepts
<a name="async"/>
-## `Async`
+## `async`
+
+...
<a name="defer"/>
-## `Defer`
-defers a dispatch on some process (i.e., a deferred asynchronous function/method invocation)
-```
-class SomeProcess : public Process<SomeProcess> {
+## `defer`
+
+Defers a `dispatch` on some process (i.e., a deferred asynchronous
+function/method invocation).
+
+~~~{.cpp}
+using namespace process;
+
+class SomeProcess : public Process<SomeProcess>
+{
public:
- void merge() {
+ void merge()
+ {
queue.get()
.then(defer(self(), [] (int i) {
- …;
+ ...;
}));
}
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 typedefer 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
+~~~
+
+`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`
+
+...
+
<a name="dispatch"/>
-dispatch ≈ message passing
-asynchronous function (method) invocation
-(think Erlang’s gen_server cast, but no call analogue … avoid blocking operations!)
+## `dispatch`
+
+`dispatch` performs asynchronous function (method) invocation (think
+Erlangs `gen_server cast`, but no `call` analogue).
+
-## `Dispatch`
-```
-class QueueProcess : public Process<QueueProcess> {
+~~~{.cpp}
+using namespace process;
+
+class QueueProcess : public Process<QueueProcess>
+{
public:
void enqueue(int i) { this->i = i; }
int dequeue() { return this->i; }
@@ -136,32 +161,46 @@ private:
};
-int main(int argc, char** argv) {
+int main(int argc, char** argv)
+{
QueueProcess process;
spawn(process);
dispatch(process, &QueueProcess::enqueue, 42);
dispatch(process, &QueueProcess::enqueue, 43);
- …;
+ ...;
}
-```
+~~~
+
<a name="future"/>
## `Future`
-A Future .... The counterpart on the producer side is a [Promise](#promise)
+
+...
+
+The counterpart on the producer side is a [Promise](#promise).
+
<a name="id"/>
-## `ID`
-The [namespace ID](@ref process::ID) contains
-[a function](@ref process::ID::generate)
-that generates unique ID strings given a prefix. This is used in the following to provide PID names.
+## 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 having an actual reference (pointer) to it (necessary for remote processes)
-```
-int main(int argc, char** argv) {
+
+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;
+
+int main(int argc, char** argv)
+{
QueueProcess process;
spawn(process);
@@ -174,43 +213,58 @@ int main(int argc, char** argv) {
return 0;
}
-```
+~~~
+
+
<a name="process"/>
## `Process`
-process ≈ thread
-creating/spawning a process is very cheap (no actual thread gets created, and no thread stack gets allocated)
-process ≈ object
-process ≈ actor
-
-each process has a “queue†of incoming “messagesâ€
-processes provide execution contexts (only one thread executing within a process at a time so no need for per process synchronization)
-Lifecycle
-```
+
+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).
+
+Each process has a queue of incoming events that it processes one at a
+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;
class MyProcess : public Process<MyProcess> {};
-int main(int argc, char** argv) {
+int main(int argc, char** argv)
+{
MyProcess process;
spawn(process);
terminate(process);
wait(process);
return 0;
}
-```
+~~~
-<a name="promise"/>
+<a name="promise"/>
## `Promise`
-```
+
+...
+
+~~~{.cpp}
+using namespace process;
+
template <typename T>
-class QueueProcess : public Process<QueueProcess<T>> {
+class QueueProcess : public Process<QueueProcess<T>>
+{
public:
- Future<T> dequeue() {
+ Future<T> dequeue()
+ {
return promise.future();
}
- void enqueue(T t) {
+ void enqueue(T t)
+ {
promise.set(t);
}
@@ -218,8 +272,10 @@ private:
Promise<T> promise;
};
-int main(int argc, char** argv) {
- …;
+
+int main(int argc, char** argv)
+{
+ ...;
Future<int> i = dispatch(process, &QueueProcess<int>::dequeue);
@@ -227,117 +283,79 @@ int main(int argc, char** argv) {
i.await();
- …;
+ ...;
}
-```
-tells caller they might need to wait … but if nobody should block, how do you wait?
-Link to then
-
+~~~
-<a name="protobuf"/>
-## `Protobuf`
<a name="route"/>
## `route`
-```
+
+~~~{.cpp}
using namespace process;
using namespace process::http;
-
-class QueueProcess : public Process<QueueProcess> {
+class QueueProcess : public Process<QueueProcess>
+{
public:
- QueueProcess() : ProcessBase(“queueâ€) {}
+ QueueProcess() : ProcessBase("queue") {}
virtual void initialize() {
- route(“/enqueueâ€, [] (Request request) {
- // Parse argument from ‘request.query’ or ‘request.body’.
+ route("/enqueue", [] (Request request)
+ {
+ // Parse argument from 'request.query' or 'request.body.
enqueue(arg);
return OK();
});
}
};
-```
-curl localhost:1234/queue/enqueue?value=42
-<a name="sequence"/>
-## `Sequence`
+// $ curl localhost:1234/queue/enqueue?value=42
+~~~
+
<a name="then"/>
-## `Then`
-```
-int main(int argc, char** argv) {
- …;
+## `Future::then`
+
+~~~{.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’.
+ // Use 'i'.
});
- …;
+ ...;
}
-```
-when future is satisfied, callbacks should be invoked …
-(1) when should a callback get invoked?
-(2) using what execution context?
-synchronously: using the current thread, blocking whatever was currently executing
-asynchronously: using a different thread than the current thread (but what thread?)
+~~~
-Link to defere <a href="#defer">Defer</a>
+When future is completed, callbacks get invoked.
<!---
-The `Option` type provides a safe alternative to using `NULL`. An `Option` can be constructed explicitely or implicitely:
-
-```
- Option<bool> o(true);
- Option<bool> o = true;
-```
-
-You can check if a value is present using `Option::isSome()` and `Option::isNone()` and retrieve the value using `Option::get()`:
-
-```
- if (!o.isNone()) {
- ... o.get() ...
- }
-```
-
-Note that the current implementation *copies* the underlying values (see [Philosophy](#philosophy) for more discussion). Nothing prevents you from using pointers, however, *the pointer will not be deleted when the Option is destructed*:
-
-```
- Option<std::string*> o = new std::string("hello world");
-```
-
-The `None` type acts as "syntactic sugar" to make using [Option](#option) less verbose. For example:
-
-```
- Option<T> foo(const Option<T>& o) {
- return None(); // Can use 'None' here.
- }
-
- ...
+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?)?
+--->
- foo(None()); // Or here.
- ...
+## Pattern/Examples
- Option<int> o = None(); // Or here.
-```
+...
-Similar to `None`, the `Some` type can be used to construct an `Option` as well. In most circumstances `Some` is unnecessary due to the implicit `Option` constructor, however, it can still be useful to remove any ambiguities as well as when embedded within collections:
-```
- Option<Option<std::string>> o = Some("42");
+## Building
- std::map<std::string, Option<std::string>> values;
- values["value1"] = None();
- values["value2"] = Some("42");
-```
---->
-##Pattern/Examples
+...
-##Building
-###Dependencies
-> NOTE: Libprocess requires the following third party libraries:
+### Dependencies
+> NOTE: Libprocess requires the following third party libraries: ...