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:44 UTC
[1/4] mesos git commit: Updated Clock::now documentation.
Repository: mesos
Updated Branches:
refs/heads/master 538dbf39e -> ffbdc78ed
Updated Clock::now documentation.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/fda8b7f7
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/fda8b7f7
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/fda8b7f7
Branch: refs/heads/master
Commit: fda8b7f76a271f4c30b6764ee417e07c2074bf1b
Parents: 538dbf3
Author: Benjamin Hindman <be...@gmail.com>
Authored: Wed Jun 3 03:40:12 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Wed Jun 3 03:40:12 2015 -0700
----------------------------------------------------------------------
3rdparty/libprocess/include/process/clock.hpp | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/fda8b7f7/3rdparty/libprocess/include/process/clock.hpp
----------------------------------------------------------------------
diff --git a/3rdparty/libprocess/include/process/clock.hpp b/3rdparty/libprocess/include/process/clock.hpp
index 4034f05..de39667 100644
--- a/3rdparty/libprocess/include/process/clock.hpp
+++ b/3rdparty/libprocess/include/process/clock.hpp
@@ -37,9 +37,11 @@ public:
lambda::function<void(const std::list<Timer>&)>&& callback);
/**
- * The current clock time for the current process that makes this call.
+ * The current clock time for either the current process that makes
+ * this call or the global clock time if not invoked from a process.
*
- * @return This process' current clock time.
+ * @return This process' current clock time or the global clock time
+ * if not invoked from a process.
*/
static Time now();
[4/4] mesos git commit: Initial clean up pass of libprocess README.md.
Posted by be...@apache.org.
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: ...
[3/4] mesos git commit: Cleanup doxygen comments.
Posted by be...@apache.org.
Cleanup doxygen comments.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/ffbdc78e
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/ffbdc78e
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/ffbdc78e
Branch: refs/heads/master
Commit: ffbdc78edfdac1be6d3b373929521ea3dce2e6d3
Parents: 929e355
Author: Benjamin Hindman <be...@gmail.com>
Authored: Wed Jun 3 06:38:00 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Wed Jun 3 06:42:28 2015 -0700
----------------------------------------------------------------------
3rdparty/libprocess/include/process/clock.hpp | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/ffbdc78e/3rdparty/libprocess/include/process/clock.hpp
----------------------------------------------------------------------
diff --git a/3rdparty/libprocess/include/process/clock.hpp b/3rdparty/libprocess/include/process/clock.hpp
index de39667..8dc7be8 100644
--- a/3rdparty/libprocess/include/process/clock.hpp
+++ b/3rdparty/libprocess/include/process/clock.hpp
@@ -28,11 +28,10 @@ public:
/**
* Initialize the clock with the specified callback that will be
* invoked whenever a batch of timers has expired.
- *
- * TODO(benh): Introduce a "channel" or listener pattern for getting
- * the expired Timers rather than passing in a callback. This might
- * mean we don't need 'initialize' or 'shutdown'.
*/
+ // TODO(benh): Introduce a "channel" or listener pattern for getting
+ // the expired Timers rather than passing in a callback. This might
+ // mean we don't need 'initialize' or 'shutdown'.
static void initialize(
lambda::function<void(const std::list<Timer>&)>&& callback);
[2/4] mesos git commit: Make Stout README.md be renderable by doxygen.
Posted by be...@apache.org.
Make Stout README.md be renderable by doxygen.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/ddcddfb5
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/ddcddfb5
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/ddcddfb5
Branch: refs/heads/master
Commit: ddcddfb5002c02b61be93ae6cac1696b56deab4d
Parents: fda8b7f
Author: Benjamin Hindman <be...@gmail.com>
Authored: Wed Jun 3 06:37:03 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Wed Jun 3 06:42:28 2015 -0700
----------------------------------------------------------------------
3rdparty/libprocess/3rdparty/stout/README.md | 128 ++++++++++++----------
1 file changed, 68 insertions(+), 60 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/ddcddfb5/3rdparty/libprocess/3rdparty/stout/README.md
----------------------------------------------------------------------
diff --git a/3rdparty/libprocess/3rdparty/stout/README.md b/3rdparty/libprocess/3rdparty/stout/README.md
index 9134677..6fc09d6 100644
--- a/3rdparty/libprocess/3rdparty/stout/README.md
+++ b/3rdparty/libprocess/3rdparty/stout/README.md
@@ -41,29 +41,30 @@ Note that the library is designed to completely avoid exceptions. See [exception
The `Option` type provides a safe alternative to using `NULL`. An `Option` can be constructed explicitely or implicitely:
-```
+~~~{.cpp}
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()`:
-```
+~~~{.cpp}
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*:
-```
+~~~{.cpp}
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) {
+~~~{.cpp}
+ Option<T> foo(const Option<T>& o)
+ {
return None(); // Can use 'None' here.
}
@@ -74,17 +75,17 @@ The `None` type acts as "syntactic sugar" to make using [Option](#option) less v
...
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:
-```
+~~~{.cpp}
Option<Option<std::string>> o = Some("42");
std::map<std::string, Option<std::string>> values;
values["value1"] = None();
values["value2"] = Some("42");
-```
+~~~
<a href="try"></a>
@@ -93,41 +94,46 @@ Similar to `None`, the `Some` type can be used to construct an `Option` as well.
A `Try` provides a mechanism to return a value or an error without throwing exceptions. Like `Option`, you can explicitely or implicitely construct a `Try`:
-```
+~~~{.cpp}
Try<bool> t(true);
Try<bool> t = true;
-```
+~~~
You can check if a value is present using `Try::isSome()` and `Try::isError()` and retrieve the value using `Try::get()` or the error via `Try::error`:
-```
+~~~{.cpp}
if (!t.isError()) {
... t.get() ...
} else {
... t.error() ...
}
-```
+~~~
A `Result` is a combination of a `Try` and an `Option`; you can think of a `Result` as semantically being equivalant to `Try<Option<T>>`. In addition to `isSome()` and `isError()` a `Result` includes `isNone()`.
The `Error` type acts as "syntactic sugar" for implicitly constructing a `Try` or `Result`. For example:
-```
- Try<bool> parse(const std::string& s) {
- if (s == "true") return true;
- else if (s == "false") return false;
- else return Error("Failed to parse string as boolean");
+~~~{.cpp}
+ Try<bool> parse(const std::string& s)
+ {
+ if (s == "true") {
+ return true;
+ } else if (s == "false") {
+ return false;
+ } else {
+ return Error("Failed to parse string as boolean");
+ }
}
Try<bool> t = parse("false");
-```
+~~~
You can also use `None` and `Some` with `Result` just like with `Option`:
-```
+~~~{.cpp}
Result<bool> r = None();
Result<bool> r = Some(true);
-```
+~~~
@@ -155,9 +161,9 @@ A collection of utilities for working with a filesystem. Currently we provide `f
A collection of utilities for doing gzip compression and decompression using `gzip::compress` and `gzip::decompress`.
-```
+~~~{.cpp}
gzip::decompress(gzip::compress("hello world"));
-```
+~~~
<a href="json"></a>
@@ -172,7 +178,7 @@ We explicitly define 'true' (`JSON::True`), 'false' (`JSON::False`), and 'null'
We could have avoided using `JSON::String` or `JSON::Number` and just used `std::string` and `double` respectively, but we choose to include them for completeness (although, this does slow compilation due to the extra template instantiations). That being said, you can use the native types in place of constructing the `JSON` wrapper. For example:
-```
+~~~{.cpp}
// {
// "foo": "value1",
// "bar": "value2",
@@ -184,11 +190,11 @@ We could have avoided using `JSON::String` or `JSON::Number` and just used `std:
object.values["bar"] = "value2";
object.values["baz"] = JSON::Number(42.0);
object.values["bam"] = 0.42;
-```
+~~~
Of course, nesting of a `JSON::Value` is also permitted as per the JSON specification:
-```
+~~~{.cpp}
// An array of objects:
// [
// { "first": "Benjamin", "last": "Hindman" },
@@ -207,7 +213,7 @@ Of course, nesting of a `JSON::Value` is also permitted as per the JSON specific
object2.values["last"] = "Hindman";
array.values.push_back(object2);
-```
+~~~
You can "render" a JSON value using `std::ostream operator <<` (or by using `stringify` (see [here](#stringify)).
@@ -252,14 +258,14 @@ There is an `os::sysctl` abstraction for getting and setting kernel state on OS
There are a handful of wrappers that make working with signals easier, including `os::pending`, `os::block`, and `os::unblock`. In addition, there is a suppression abstraction that enables executing a block a code while blocking a signal. Consider writing to a pipe which may raise a SIGPIPE if the pipe has been closed. Using `suppress` you can do:
-```
+~~~{.cpp}
suppress (SIGPIPE) {
write(fd, data, size);
if (errno == EPIPE) {
// The pipe has been closed!
}
}
-```
+~~~
<a href="path"></a>
@@ -288,11 +294,11 @@ Helpers for reading and writing protobufs from files and file descriptors are pr
There is also a protobuf to JSON converter via `JSON::Protobuf` that enables serializing a protobuf into JSON:
-```
+~~~{.cpp}
google::protobuf::Message message;
... fill in message ...
JSON::Object o = JSON::Protobuf(message);
-```
+~~~
<a href="strings"></a>
@@ -311,9 +317,11 @@ String formatting is provided via `strings::format`. The `strings::format` funct
One frustration with existing command line flags libraries was the burden they put on writing tests that attempted to have many different instantiations of the flags. For example, running two instances of the same component within a test where each instance was started with different command line flags. To solve this, we provide a command line flags abstraction called `Flags` (in the `flags` namespace) that you can extend to define your own flags:
-```
- struct MyFlags : flags::Flags {
- MyFlags() {
+~~~{.cpp}
+ struct MyFlags : flags::Flags
+ {
+ MyFlags()
+ {
// A flag with a default value.
add(&MyFlags::foo,
"foo",
@@ -330,11 +338,11 @@ One frustration with existing command line flags libraries was the burden they p
int foo;
Option<std::string> bar;
};
-```
+~~~
You can then load the flags via `argc` and `argv` via:
-```
+~~~{.cpp}
MyFlags flags;
Try<Nothing> load = flags.load(None(), argc, argv);
@@ -342,14 +350,14 @@ You can then load the flags via `argc` and `argv` via:
... flags.foo ...
... flags.bar.isSome() ... flags.bar.get() ...
-```
+~~~
You can load flags from the environment in addition to `argc` and `argv` by specifying a prefix to use when looking for flags:
-```
+~~~{.cpp}
MyFlags flags;
Try<Nothing> load = flags.load("PREFIX_", argc, argv);
-```
+~~~
Then both PREFIX_foo and PREFIX_bar will be loaded from the environemnt as well as possibly from on the command line.
@@ -384,44 +392,44 @@ There are a handful of types and utilties that fall into the miscellaneous categ
Used to represent some magnitude of bytes, i.e., kilobytes, megabytes, gigabytes, etc. The main way to construct a `Bytes` is to invoke `Bytes::parse` which expects a string made up of a number and a unit, i.e., `42B`, `42MB`, `42GB`, `42TB`. For each of the supported units there are associated types: `Megabytes`, `Gigabytes`, `Terabytes`. Each of these types inherit from `Bytes` and can be used anywhere a `Bytes` is expected, for example:
-```
+~~~{.cpp}
Try<Bytes> bytes = Bytes::parse("32MB");
Bytes bytes = Megabytes(10);
-```
+~~~
There are operators for comparing (equal to, greater than or less than, etc) and manipulating (addition, subtraction, etc) `Bytes` objects, as well as a `std::ostream operator <<` overload (thus making them stringifiable, see [here](#stringify)). For example:
-```
+~~~{.cpp}
Try<Bytes> bytes = Bytes::parse("32MB");
Bytes tengb = Gigabytes(10);
Bytes onegb = Megabytes(1024);
stringify(tengb + onegb); // Yields "11GB".
-```
+~~~
#### `Duration`
Used to represent some duration of time. The main way to construct a `Duration` is to invoke `Duration::parse` which expects a string made up of a number and a unit, i.e., `42ns`, `42us`, `42ms`, `42secs`, `42mins`, `42hrs`, `42days`, `42weeks`. For each of the supported units there are associated types: `Nanoseconds`, `Microseconds`, `Milliseconds`, `Seconds`, `Minutes`, `Hours`, `Days`, `Weeks`. Each of these types inherit from `Duration` and can be used anywhere a `Duration` is expected, for example:
-```
+~~~{.cpp}
Duration d = Seconds(5);
-```
+~~~
There are operators for comparing (equal to, greater than or less than, etc) and manipulating (addition, subtraction, etc) `Duration` objects, as well as a `std::ostream operator <<` overload (thus making them stringifiable, see [here](#stringify)). Note that the `std::ostream operator <<` overload formats the output (including the unit) based on the magnitude, for example:
-```
+~~~{.cpp}
stringify(Seconds(42)); // Yields "42secs".
stringify(Seconds(120)); // Yields "2mins".
-```
+~~~
#### `Stopwatch`
-A datastructure for recording elapsed time (according to the underlying operating system clock):
+A data structure for recording elapsed time (according to the underlying operating system clock):
-```
+~~~{.cpp}
Stopwatch stopwatch;
stopwatch.start();
@@ -430,7 +438,7 @@ A datastructure for recording elapsed time (according to the underlying operatin
stopwatch.stop();
assert(elapsed <= stopwatch.elapsed());
-```
+~~~
#### `UUID`
@@ -444,9 +452,9 @@ A wrapper around `boost::uuid` with a simpler interface.
A macro for exiting an application without generating a signal (such as from `assert`) or a stack trace (such as from Google logging's `CHECK` family of macros). This is useful if you want to exit the program with an error message:
-```
+~~~{.cpp}
EXIT(42) << "You've provided us bad input ...";
-```
+~~~
Note that a newline is automatically appended and the processes exit status is set to 42.
@@ -457,7 +465,7 @@ Note that a newline is automatically appended and the processes exit status is s
Macros for looping over collections:
-```
+~~~{.cpp}
std::list<std::string> l;
foreach (std::string s, l) {}
@@ -470,7 +478,7 @@ Macros for looping over collections:
foreachkey (const std::string& s, m) {}
foreachvalue (int i, m) {}
-```
+~~~
#### `numify`
@@ -493,13 +501,13 @@ Converts arbitrary types into strings by attempting to use an overloaded `std::o
You can give every thread it's own copy of some data using the `ThreadLocal` abstraction:
-```
+~~~{.cpp}
ThreadLocal<std::string> local;
local = new std::string("hello");
local->append(" world");
std::string* s = local;
assert(*s == "hello world");
-```
+~~~
<a href="testing"></a>
@@ -509,7 +517,7 @@ You can give every thread it's own copy of some data using the `ThreadLocal` abs
There are some macros provided for integration with gtest that make the tests less verbose while providing better messages when tests do fail:
-```
+~~~{.cpp}
Try<int> t = foo();
// Rather than:
@@ -517,7 +525,7 @@ There are some macros provided for integration with gtest that make the tests le
// Just do:
ASSERT_SOME(t);
-```
+~~~
There available macros include `ASSERT_SOME`, `EXPECT_SOME`, `ASSERT_NONE`, `EXPECT_NONE`, `ASSERT_ERROR`, `EXPECT_ERROR`, `ASSERT_SOME_EQ`, `EXPECT_SOME_EQ`, `ASSERT_SOME_TRUE`, `EXPECT_SOME_TRUE`, `ASSERT_SOME_FALSE`, `EXPECT_SOME_FALSE`.