You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by dl...@apache.org on 2015/07/01 20:55:33 UTC
svn commit: r1688707 [3/7] - in /mesos/site: publish/ publish/documentation/
publish/documentation/allocation-module/
publish/documentation/app-framework-development-guide/
publish/documentation/clang-format/ publish/documentation/configuration/
publis...
Added: mesos/site/publish/documentation/latest/reservation/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/latest/reservation/index.html?rev=1688707&view=auto
==============================================================================
--- mesos/site/publish/documentation/latest/reservation/index.html (added)
+++ mesos/site/publish/documentation/latest/reservation/index.html Wed Jul 1 18:55:31 2015
@@ -0,0 +1,404 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title></title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+ <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
+ <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
+
+ <link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />
+
+
+
+ <!-- Google Analytics Magic -->
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-20226872-1']);
+ _gaq.push(['_setDomainName', 'apache.org']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+ </head>
+ <body>
+ <!-- magical breadcrumbs -->
+ <div class="topnav">
+ <ul class="breadcrumb">
+ <li>
+ <div class="dropdown">
+ <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
+ <li><a href="http://www.apache.org">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </div>
+ </li>
+ <li><a href="http://mesos.apache.org">Apache Mesos</a></li>
+
+
+ <li><a href="/documentation
+/">Documentation
+</a></li>
+
+
+ </ul><!-- /breadcrumb -->
+ </div>
+
+ <!-- navbar excitement -->
+ <div class="navbar navbar-static-top" role="navigation">
+ <div class="navbar-inner">
+ <div class="container">
+ <a href="/" class="logo"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo" /></a>
+ <div class="nav-collapse">
+ <ul class="nav nav-pills navbar-right">
+ <li><a href="/gettingstarted/">Getting Started</a></li>
+ <li><a href="/documentation/latest/">Documentation</a></li>
+ <li><a href="/downloads/">Downloads</a></li>
+ <li><a href="/community/">Community</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div><!-- /.navbar -->
+
+ <div class="container">
+
+ <div class="row-fluid">
+ <div class="col-md-4">
+ <h4>If you're new to Mesos</h4>
+ <p>See the <a href="/gettingstarted/">getting started</a> page for more information about downloading, building, and deploying Mesos.</p>
+
+ <h4>If you'd like to get involved or you're looking for support</h4>
+ <p>See our <a href="/community/">community</a> page for more details.</p>
+ </div>
+ <div class="col-md-8">
+ <h1>Reservation</h1>
+
+<p>Mesos provides mechanisms to <strong>reserve</strong> resources in specific slaves.
+The concept was first introduced with <strong>static reservation</strong> in 0.14.0
+which enabled operators to specify the reserved resources on slave startup.
+This was extended with <strong>dynamic reservation</strong> in 0.23.0 which enabled operators
+and authorized <strong>frameworks</strong> to dynamically reserve resources in the cluster.</p>
+
+<p>No breaking changes were introduced with dynamic reservation, which means the
+existing static reservation mechanism continues to be fully supported.</p>
+
+<p>In both types of reservations, resources are reserved for a <strong>role</strong>.</p>
+
+<h2>Static Reservation (since 0.14.0)</h2>
+
+<p>An operator can configure a slave with resources reserved for a role.
+The reserved resources are specified via the <code>--resources</code> flag.
+For example, suppose we have 12 CPUs and 6144 MB of RAM available on a slave and
+that we want to reserve 8 CPUs and 4096 MB of RAM for the <code>ads</code> role.
+We start the slave like so:</p>
+
+<pre><code> $ mesos-slave \
+ --master=<ip>:<port> \
+ --resources="cpus:4;mem:2048;cpus(ads):8;mem(ads):4096"
+</code></pre>
+
+<p>We now have 8 CPUs and 4096 MB of RAM reserved for <code>ads</code> on this slave.</p>
+
+<p><strong>CAVEAT:</strong> In order to modify a static reservation, the operator must drain and
+ restart the slave with the new configuration specifed in the
+ <code>--resources</code> flag.</p>
+
+<p><strong>NOTE:</strong> This feature is supported for backwards compatibility.
+ The recommended approach is to specify the total resources available
+ on the slave as unreserved via the <code>--resources</code> flag and manage
+ reservations dynamically via the master HTTP endpoints.</p>
+
+<h2>Dynamic Reservation (since 0.23.0)</h2>
+
+<p>As mentioned in <a href="#static-reservation-since-0140">Static Reservation</a>, specifying the
+reserved resources via the <code>--resources</code> flag makes the reservation static.
+This is, statically reserved resources cannot be reserved for another role nor
+be unreserved. Dynamic Reservation enables operators and authorized frameworks
+to reserve and unreserve resources post slave-startup.</p>
+
+<p>We require a <code>principal</code> from the operator or framework in order to
+authenticate/authorize the operations. <a href="/documentation/latest/authorization/">Authorization</a> is
+specified via the existing ACL mechanism. (<em>Coming Soon</em>)</p>
+
+<ul>
+<li><code>Offer::Operation::Reserve</code> and <code>Offer::Operation::Unreserve</code> messages are
+available for <strong>frameworks</strong> to send back via the <code>acceptOffers</code> API as a
+response to a resource offer.</li>
+<li><code>/reserve</code> and <code>/unreserve</code> HTTP endpoints are available for <strong>operators</strong>
+to manage dynamic reservations through the master. (<em>Coming Soon</em>).</li>
+</ul>
+
+
+<p>In the following sections, we will walk through examples of each of the
+interfaces described above.</p>
+
+<h3><code>Offer::Operation::Reserve</code></h3>
+
+<p>A framework is able to reserve resources through the resource offer cycle.
+Suppose we receive a resource offer with 12 CPUs and 6144 MB of RAM unreserved.</p>
+
+<pre><code> {
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 12 },
+ "role": "*",
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 6144 },
+ "role": "*",
+ }
+ ]
+ }
+</code></pre>
+
+<p>We can reserve 8 CPUs and 4096 MB of RAM by sending the following
+<code>Offer::Operation</code> message. <code>Offer::Operation::Reserve</code> has a <code>resources</code> field
+which we specify with the resources to be reserved. We need to expicitly set
+the <code>role</code> and <code>principal</code> fields with the framework’s role and principal.</p>
+
+<pre><code> {
+ "type": Offer::Operation::RESERVE,
+ "reserve": {
+ "resources": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ }
+ ]
+ }
+ }
+</code></pre>
+
+<p>The subsequent resource offer will <strong>contain</strong> the following reserved resources:</p>
+
+<pre><code> {
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ ]
+ }
+</code></pre>
+
+<h3><code>Offer::Operation::Unreserve</code></h3>
+
+<p>A framework is able to unreserve resources through the resource offer cycle.
+In <a href="#offeroperationreserve">Offer::Operation::Reserve</a>, we reserved 8 CPUs
+and 4096 MB of RAM for our <code>role</code>. The master will continue to offer these
+resources to our <code>role</code>. Suppose we would like to unreserve these resources.
+First, we receive a resource offer (copy/pasted from above):</p>
+
+<pre><code> {
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ ]
+ }
+</code></pre>
+
+<p>We unreserve the 8 CPUs and 4096 MB of RAM by sending the following
+<code>Offer::Operation</code> message. <code>Offer::Operation::Unreserve</code> has a <code>resources</code> field
+which we specify with the resources to be unreserved.</p>
+
+<pre><code> {
+ "type": Offer::Operation::UNRESERVE,
+ "unreserve": {
+ "resources": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "role": <framework_role>,
+ "reservation": {
+ "principal": <framework_principal>
+ }
+ }
+ ]
+ }
+ }
+</code></pre>
+
+<p>The unreserved resources may now be offered to other frameworks.</p>
+
+<h3><code>/reserve</code> (<em>Coming Soon</em>)</h3>
+
+<p>Suppose we want to reserve 8 CPUs and 4096 MB of RAM for the <code>ads</code> role on
+a slave with id=<code><slave_id></code>. We send an HTTP POST request to the <code>/reserve</code>
+HTTP endpoint like so:</p>
+
+<pre><code> $ curl -i \
+ -u <operator_principal>:<password> \
+ -d slaveId=<slave_id> \
+ -d resources='[ \
+ { \
+ "name": "cpus", \
+ "type": "SCALAR", \
+ "scalar": { "value": 8 }, \
+ "role": "ads", \
+ "reservation": { \
+ "principal": <operator_principal> \
+ } \
+ }, \
+ { \
+ "name": "mem", \
+ "type": "SCALAR", \
+ "scalar": { "value": 4096 }, \
+ "role": "ads", \
+ "reservation": { \
+ "principal": <operator_principal> \
+ } \
+ } \
+ ]' \
+ -X POST http://<ip>:<port>/master/reserve
+</code></pre>
+
+<p>The user receives one of the following HTTP responses:</p>
+
+<ul>
+<li><code>200 OK</code>: Success</li>
+<li><code>400 BadRequest</code>: Invalid arguments (e.g. missing parameters).</li>
+<li><code>401 Unauthorized</code>: Unauthorized request.</li>
+<li><code>409 Conflict</code>: Insufficient resources to satisfy the reserve operation.</li>
+</ul>
+
+
+<h3><code>/unreserve</code> (<em>Coming Soon</em>)</h3>
+
+<p>Suppose we want to unreserve the resources that we dynamically reserved above.
+We can send an HTTP POST request to the <code>/unreserve</code> HTTP endpoint like so:</p>
+
+<pre><code> $ curl -i \
+ -u <operator_principal>:<password> \
+ -d slaveId=<slave_id> \
+ -d resources='[ \
+ { \
+ "name": "cpus", \
+ "type": "SCALAR", \
+ "scalar": { "value": 8 }, \
+ "role": "ads", \
+ "reservation": { \
+ "principal": <operator_principal> \
+ } \
+ }, \
+ { \
+ "name": "mem", \
+ "type": "SCALAR", \
+ "scalar": { "value": 4096 }, \
+ "role": "ads", \
+ "reservation": { \
+ "principal": <operator_principal> \
+ } \
+ } \
+ ]' \
+ -X POST http://<ip>:<port>/master/unreserve
+</code></pre>
+
+<p>The user receives one of the following HTTP responses:</p>
+
+<ul>
+<li><code>200 OK</code>: Success</li>
+<li><code>400 BadRequest</code>: Invalid arguments (e.g. missing parameters).</li>
+<li><code>401 Unauthorized</code>: Unauthorized request.</li>
+<li><code>409 Conflict</code>: Insufficient resources to satisfy unreserve operation.</li>
+</ul>
+
+
+ </div>
+</div>
+
+
+ <hr>
+
+ <!-- footer -->
+ <div class="footer">
+ <p>© 2012-2014 <a href="http://apache.org">The Apache Software Foundation</a>.
+ Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.<p>
+ </div><!-- /footer -->
+
+ </div> <!-- /container -->
+
+ <!-- JS -->
+ <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
+ </body>
+</html>
\ No newline at end of file
Modified: mesos/site/publish/documentation/latest/upgrades/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/latest/upgrades/index.html?rev=1688707&r1=1688706&r2=1688707&view=diff
==============================================================================
--- mesos/site/publish/documentation/latest/upgrades/index.html (original)
+++ mesos/site/publish/documentation/latest/upgrades/index.html Wed Jul 1 18:55:31 2015
@@ -89,6 +89,12 @@
<p><strong>NOTE</strong> In order to enable decorator modules to remove metadata (environment variables or labels), we changed the meaning of the return value for decorator hooks in Mesos 0.23.0. Please refer to the modules documentation for more details.</p>
+<p><strong>NOTE</strong> Slave ping timeouts are now configurable on the master via <code>--slave_ping_timeout</code> and <code>--max_slave_ping_timeouts</code>. Slaves should be upgraded to 0.23.x before changing these flags.</p>
+
+<p><strong>NOTE</strong> A new scheduler driver API, <code>acceptOffers</code>, has been introduced. This is a more general version of the <code>launchTasks</code> API, which allows the scheduler to accept an offer and specify a list of operations (Offer.Operation) to perform using the resources in the offer. Currently, the supported operations include LAUNCH (launching tasks), RESERVE (making dynamic reservations), UNRESERVE (releasing dynamic reservations), CREATE (creating persistent volumes) and DESTROY (releasing persistent volumes). Similar to the <code>launchTasks</code> API, any unused resources will be considered declined, and the specified filters will be applied on all unused resources.</p>
+
+<p><strong>NOTE</strong> The Resource protobuf has been extended to include more metadata for supporting persistence (DiskInfo), dynamic reservations (ReservationInfo) and oversubscription (RevocableInfo). You must not combine two Resource objects if they have different metadata.</p>
+
<h2>Upgrading from 0.21.x to 0.22.x</h2>
<p><strong>NOTE</strong> Slave checkpoint flag has been removed as it will be enabled for all
@@ -175,13 +181,13 @@ Please refer to the metrics/snapshot end
<p>To ensure a smooth upgrade, we recommend to upgrade your python framework and executor first. You will be able to either import using the new configuration or the old. Replace the existing imports with something like the following:</p>
-<pre><code> try:
- from mesos.native import MesosExecutorDriver, MesosSchedulerDriver
- from mesos.interface import Executor, Scheduler
- from mesos.interface import mesos_pb2
- except ImportError:
- from mesos import Executor, MesosExecutorDriver, MesosSchedulerDriver, Scheduler
- import mesos_pb2
+<pre><code>try:
+ from mesos.native import MesosExecutorDriver, MesosSchedulerDriver
+ from mesos.interface import Executor, Scheduler
+ from mesos.interface import mesos_pb2
+except ImportError:
+ from mesos import Executor, MesosExecutorDriver, MesosSchedulerDriver, Scheduler
+ import mesos_pb2
</code></pre>
<p><strong>NOTE</strong>: If you’re using a pure language binding, please ensure that it sends status update acknowledgements through the master before upgrading.</p>
Modified: mesos/site/publish/documentation/mesos-c++-style-guide/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-c%2B%2B-style-guide/index.html?rev=1688707&r1=1688706&r2=1688707&view=diff
==============================================================================
--- mesos/site/publish/documentation/mesos-c++-style-guide/index.html (original)
+++ mesos/site/publish/documentation/mesos-c++-style-guide/index.html Wed Jul 1 18:55:31 2015
@@ -95,7 +95,7 @@
</ul>
-<pre><code>Try(State _state, T* _t = NULL, const std::string& _message = "")
+<pre><code class="{.cpp}">Try(State _state, T* _t = NULL, const std::string& _message = "")
: state(_state), t(_t), message(_message) {}
</code></pre>
@@ -105,7 +105,7 @@
</ul>
-<pre><code>// You can pass-by-value in ProtobufProcess::install() handlers.
+<pre><code class="{.cpp}">// You can pass-by-value in ProtobufProcess::install() handlers.
void Slave::statusUpdate(StatusUpdate update, const UPID& pid)
{
...
@@ -178,7 +178,7 @@ void Slave::statusUpdate(StatusUpdate up
</ul>
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
allocator->resourcesRecovered(frameworkId, slaveId, resources, filters);
// 2: Don't use.
@@ -215,7 +215,7 @@ allocator->resourcesRecovered(
</ul>
-<pre><code>Try<Duration> failoverTimeout =
+<pre><code class="{.cpp}">Try<Duration> failoverTimeout =
Duration::create(FrameworkInfo().failover_timeout());
</code></pre>
@@ -232,7 +232,7 @@ allocator->resourcesRecovered(
<p>We disallow capturing <strong>temporaries</strong> by reference. See <a href="https://issues.apache.org/jira/browse/MESOS-2629">MESOS-2629</a> for the rationale.</p>
-<pre><code>Future<Nothing> f() { return Nothing(); }
+<pre><code class="{.cpp}">Future<Nothing> f() { return Nothing(); }
Future<bool> g() { return false; }
struct T
@@ -282,7 +282,7 @@ const T t = T("Hello").member();
</ul>
-<pre><code>hashmap<string, hashset<int>> index;
+<pre><code class="{.cpp}">hashmap<string, hashset<int>> index;
// 1: Ok.
const hashset<int>& values = index[2];
@@ -311,49 +311,45 @@ s += "world"; // THIS IS A DANGLING REFE
<h2>File Headers</h2>
<ul>
-<li>Mesos source files must contain the “ASF” header:</li>
-</ul>
-
+<li><p>Mesos source files must contain the “ASF” header:</p>
-<pre><code>/**
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-</code></pre>
+<pre><code> /**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+</code></pre></li>
+<li><p>Stout and libprocess source files must contain the “Apache License Version 2.0” header:</p>
-<ul>
-<li>Stout and libprocess source files must contain the “Apache License Version 2.0” header:</li>
+<pre><code> /**
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License
+ */
+</code></pre></li>
</ul>
-<pre><code>/**
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License
- */
-</code></pre>
-
<h2>C++11</h2>
<p>We support C++11 and require GCC 4.8+ or Clang 3.5+ compilers. The whitelist of supported C++11 features is:</p>
@@ -365,7 +361,7 @@ s += "world"; // THIS IS A DANGLING REFE
</ul>
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
const auto& i = values.find(keys.front());
// Compare with
const typename map::iterator& i = values.find(keys.front());
@@ -401,20 +397,28 @@ Try<Owned<LocalAuthorizer>>
<li><code>shared_from_this()</code></li>
</ul>
</li>
-<li><p>Lambdas!</p>
+<li>Lambdas!
<ul>
-<li><p>Don’t put a space between the capture list and the parameter list:</p>
+<li>Don’t put a space between the capture list and the parameter list:</li>
+</ul>
+</li>
+</ul>
+
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
[]() { ...; };
// 2: Don't use.
[] () { ...; };
-</code></pre></li>
-<li><p>Prefer default capture by value, explicit capture by value, then capture by reference. To avoid dangling-pointer bugs, <em>never</em> use default capture by reference:</p>
+</code></pre>
-<pre><code>// 1: OK.
+<ul>
+<li>Prefer default capture by value, explicit capture by value, then capture by reference. To avoid dangling-pointer bugs, <em>never</em> use default capture by reference:</li>
+</ul>
+
+
+<pre><code class="{.cpp}">// 1: OK.
[=]() { ... }; // Default capture by value.
[n]() { ... }; // Explicit capture by value.
[&n]() { ... }; // Explicit capture by reference.
@@ -422,26 +426,42 @@ Try<Owned<LocalAuthorizer>>
// 2: Don't use.
[&]() { ... }; // Default capture by reference.
-</code></pre></li>
-<li><p>Use <code>mutable</code> only when absolutely necessary.</p>
+</code></pre>
+
+<ul>
+<li>Use <code>mutable</code> only when absolutely necessary.</li>
+</ul>
+
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
[]() mutable { ...; };
-</code></pre></li>
-<li><p>Feel free to ignore the return type by default, adding it as necessary to appease the compiler or be more explicit for the reader.</p>
+</code></pre>
+
+<ul>
+<li>Feel free to ignore the return type by default, adding it as necessary to appease the compiler or be more explicit for the reader.</li>
+</ul>
+
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
[]() { return true; };
[]() -> bool { return ambiguous(); };
-</code></pre></li>
-<li><p>Feel free to use <code>auto</code> when naming a lambda expression:</p>
+</code></pre>
-<pre><code>// 1: OK.
+<ul>
+<li>Feel free to use <code>auto</code> when naming a lambda expression:</li>
+</ul>
+
+
+<pre><code class="{.cpp}">// 1: OK.
auto lambda = []() { ...; };
-</code></pre></li>
-<li><p>Format lambdas similar to how we format functions and methods. Feel free to let lambdas be one-liners:</p>
+</code></pre>
+
+<ul>
+<li>Format lambdas similar to how we format functions and methods. Feel free to let lambdas be one-liners:</li>
+</ul>
+
-<pre><code>// 1: OK.
+<pre><code class="{.cpp}">// 1: OK.
auto lambda = []() {
...;
};
@@ -450,16 +470,22 @@ auto lambda = []() {
auto lambda = []() { ...; };
</code></pre>
-<p>Feel free to inline lambdas within function arguments:</p>
+<ul>
+<li>Feel free to inline lambdas within function arguments:</li>
+</ul>
+
-<pre><code>instance.method([]() {
+<pre><code class="{.cpp}">instance.method([]() {
...;
});
</code></pre>
-<p>Chain function calls on a newline after the closing brace of the lambda and the closing parenthesis of function call:</p>
+<ul>
+<li>Chain function calls on a newline after the closing brace of the lambda and the closing parenthesis of function call:</li>
+</ul>
-<pre><code>// 1: OK.
+
+<pre><code class="{.cpp}">// 1: OK.
instance
.method([]() {
...;
@@ -493,9 +519,12 @@ instance.method([]() {
});
</code></pre>
-<p>Wrap capture lists indepedently of parameters, <em>use the same formatting as if the capture list were template parameters</em>:</p>
+<ul>
+<li>Wrap capture lists indepedently of parameters, <em>use the same formatting as if the capture list were template parameters</em>:</li>
+</ul>
-<pre><code>// 1: OK.
+
+<pre><code class="{.cpp}">// 1: OK.
function([&capture1, &capture2, &capture3](
const T1& p1, const T2& p2, const T3& p3) {
...;
@@ -512,7 +541,6 @@ auto lambda = [&capture1, &captu
...;
};
-
auto lambda =
[&capture1, &capture2, &capture3](
const T1& p1, const T2& p2, const T3& p3) {
@@ -568,13 +596,13 @@ auto lambda = [&capture1,
&capture3,
&capture4](const T1& p1, const T2& p2) {
...;
-};
+ };
// 4: Don't use.
function([&capture1,
- &capture2,
- &capture3,
- &capture4](
+ &capture2,
+ &capture3,
+ &capture4](
const T1& p1, const T2& p2, const T3& p3) {
...;
});
@@ -596,7 +624,7 @@ function([&capture1,
const T2& p2,
const T3& p3) {
...;
-});
+ });
auto lambda = [&capture1,
&capture2,
@@ -649,12 +677,52 @@ auto lambda = [
const T4& p4) {
...;
};
-</code></pre></li>
-</ul>
-</li>
+</code></pre>
+
+<ul>
<li><p>Unrestricted Union.</p>
<p>Like the pre-existing <code>union</code>, we can overlap storage allocation for objects that never exist simultaneously. However, with C++11 we are no longer <em>restricted to having only non-POD types in unions</em>. Adding non-POD types to unions complicates things, however, because we need to make sure to properly call constructors and destructors. Therefore, only use unrestricted unions (i.e., unions with non-POD types) when the union has only a single field. What does this buy us? Now we can avoid dynamic memory allocations for “container” like types, e.g., <code>Option</code>, <code>Try</code>, <code>Result</code>, etc. In effect, we treat the union like a dynamic allocation, calling <em>placement new</em>, <code>new (&t) T(...)</code> anyplace we would have just called <code>new T(...)</code> and the destructor <code>t.~T()</code> anyplace we would have called <code>delete t</code>.</p></li>
+<li><p>Constant expressions.</p>
+
+<p>Constant expressions allow the declaration of static non-POD objects while eliminating the unpredictable runtime initialization and destruction issues normally encountered, helping eliminate macros and hard-coded literals without sacrificing performance and type safety. Changes which require converting from <code>constexpr</code> to <code>const</code> can propagate through the dependency tree requiring that dependent <code>constexpr</code> uses also be converted to <code>const</code>, hence we avoid using <code>constexpr</code> in complex functions.</p>
+
+<p><code>constexpr</code> behaves as a combination of <code>inline</code> and <code>const</code> and hence must be defined before use in another <code>constexpr</code>.</p>
+
+<p>Prefer <code>constexpr to</code>const<code>for all constant POD declarations,</code>constexpr<code></code>char<code>arrays are preferred to</code>const<code></code>string` literals.
+```
+// OK
+constexpr char LITERAL[] = “value”;</p>
+
+<p>// Not OK - not available at compile time for optimization and
+// definition required in a separate compilation module.
+const char LITERAL[];</p>
+
+<p>// Not OK - uncertain initialization order, cannot be used in other
+// constexpr statements.
+const string LITERAL(“value”);</p>
+
+<pre><code>`constexpr` functions are evaluated at compile time if all their arguments are constant expressions. Otherwise they default to initialization at runtime. However `constexpr` functions are limited in that they cannot perform dynamic casts, memory allocation or calls to non-constexpr functions. Prefer `constexpr` over const inline functions.
+</code></pre>
+
+<p>constexpr size_t MIN = 200;
+constexpr size_t MAX = 1000;
+constexpr size_t SPAN() { return MAX-MIN; }
+int array[SPAN()];
+<code>
+Const expression constructors allow object initialization at compile time provided that all the constructor arguments are constexpr and the constuctor body is empty, i.e. all initialization is performed in the initialization list. Classes which provide constexpr constructors should normally also provide constexpr copy constructors to allow the class to be used in the return value from a constexpr function.
+</code>
+class C
+{
+public:
+ constexpr C(int <em>i) : i(</em>i) {};
+ constexpr C(const C& c) : i(c.i) {}
+private:
+ const int i;
+};</p>
+
+<p>```
+C++11 does not provide constexpr string or containers in the STL and hence constexpr cannot be used for any class using stout’s Error() class.</p></li>
</ul>
Added: mesos/site/publish/documentation/mesos-documentation-guide/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-documentation-guide/index.html?rev=1688707&view=auto
==============================================================================
--- mesos/site/publish/documentation/mesos-documentation-guide/index.html (added)
+++ mesos/site/publish/documentation/mesos-documentation-guide/index.html Wed Jul 1 18:55:31 2015
@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title></title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+ <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
+ <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
+
+ <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />
+
+
+
+ <!-- Google Analytics Magic -->
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-20226872-1']);
+ _gaq.push(['_setDomainName', 'apache.org']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+ </head>
+ <body>
+ <!-- magical breadcrumbs -->
+ <div class="topnav">
+ <ul class="breadcrumb">
+ <li>
+ <div class="dropdown">
+ <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
+ <li><a href="http://www.apache.org">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </div>
+ </li>
+ <li><a href="http://mesos.apache.org">Apache Mesos</a></li>
+
+
+ <li><a href="/documentation
+/">Documentation
+</a></li>
+
+
+ </ul><!-- /breadcrumb -->
+ </div>
+
+ <!-- navbar excitement -->
+ <div class="navbar navbar-static-top" role="navigation">
+ <div class="navbar-inner">
+ <div class="container">
+ <a href="/" class="logo"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo" /></a>
+ <div class="nav-collapse">
+ <ul class="nav nav-pills navbar-right">
+ <li><a href="/gettingstarted/">Getting Started</a></li>
+ <li><a href="/documentation/latest/">Documentation</a></li>
+ <li><a href="/downloads/">Downloads</a></li>
+ <li><a href="/community/">Community</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div><!-- /.navbar -->
+
+ <div class="container">
+
+ <div class="row-fluid">
+ <div class="col-md-4">
+ <h4>If you're new to Mesos</h4>
+ <p>See the <a href="/gettingstarted/">getting started</a> page for more information about downloading, building, and deploying Mesos.</p>
+
+ <h4>If you'd like to get involved or you're looking for support</h4>
+ <p>See our <a href="/community/">community</a> page for more details.</p>
+ </div>
+ <div class="col-md-8">
+ <h1>Mesos Documentation Guide</h1>
+
+<p>Documentation is an integral part of every good feature. It describes the intended usage and enables new users to start using and understanding the feature.</p>
+
+<p>We have three different kinds of documentation:</p>
+
+<ol>
+<li><a href="/documentation/latest/mesos-markdown-style-guide/">MarkDown User Guides</a></li>
+</ol>
+
+
+<p> User guides and non-code technical documentation are stored in markdown files in the <code>docs/</code> folder. These files get rendered for the <a href="http://mesos.apache.org/documentation/latest/">online documentation</a>.</p>
+
+<ol>
+<li><a href="/documentation/latest/mesos-doxygen-style-guide/">Doxygen API Documentation and Developer Guides as part of source code</a></li>
+</ol>
+
+
+<p> Doxygen API documentation needs only to be applied to source code parts that
+ constitute an interface for which we want to generate Mesos API documentation
+ files. Implementation code that does not participate in this should still be
+ enhanced by source code comments as appropriate, but these comments should not follow the doxygen style.</p>
+
+<p> Substantial libraries, components, and subcomponents of the Mesos system such as
+ stout, libprocess, master, slave, containerizer, allocator, and others
+ should have an overview page in markdown format that explains their
+ purpose, overall structure, and general use. This can even be a complete developer guide.</p>
+
+<ol>
+<li>Regular source code documentation</li>
+</ol>
+
+
+<p> All other source code comments must follow the <a href="https://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Comments">Google Style Guide</a>.</p>
+
+<h2>Conventions</h2>
+
+<p>We follow the <a href="https://www.ietf.org/rfc/rfc2119.txt">IETF RFC 2119</a>
+on how to use words such as “must”, “should”, “can”,
+and other requirement-related notions.</p>
+
+ </div>
+</div>
+
+
+ <hr>
+
+ <!-- footer -->
+ <div class="footer">
+ <p>© 2012-2014 <a href="http://apache.org">The Apache Software Foundation</a>.
+ Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.<p>
+ </div><!-- /footer -->
+
+ </div> <!-- /container -->
+
+ <!-- JS -->
+ <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
+ </body>
+</html>
\ No newline at end of file
Modified: mesos/site/publish/documentation/mesos-doxygen-style-guide/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-doxygen-style-guide/index.html?rev=1688707&r1=1688706&r2=1688707&view=diff
==============================================================================
--- mesos/site/publish/documentation/mesos-doxygen-style-guide/index.html (original)
+++ mesos/site/publish/documentation/mesos-doxygen-style-guide/index.html Wed Jul 1 18:55:31 2015
@@ -89,57 +89,7 @@ using <a href="http://www.doxygen.org">D
There is an ongoing, incremental effort with the goal to document all public Mesos, libprocess, and stout APIs this way.
For now, existing code may not follow these guidelines, but new code should.</p>
-<h2>Preliminaries</h2>
-
-<p>We follow the <a href="https://www.ietf.org/rfc/rfc2119.txt">IETF RFC2119</a>
-on how to use words such as “must”, “should”, “can”,
-and other requirement-related notions.</p>
-
-<h2>Building Doxygen Documentation</h2>
-
-<p>As of right now, the Doxygen documentation should be built from the <em>build</em> subdirectory using <em>doxygen ../Doxyfile</em> . The documentation will then be generated into the <em>./doxygen</em> subdirectory.
-Todo: We should create a regular make target.</p>
-
-<h2>Doxygen Tags</h2>
-
-<p><em>When following these links be aware that the doxygen documentation is using another syntax in that @param is explained as \param.</em></p>
-
-<ul>
-<li><a href="http://doxygen.org/manual/commands.html#cmdparam">@param</a> Describes function parameters.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdreturn">@return</a> Describes return values.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdsa">@see</a> Describes a cross-reference to classes, functions, methods, variables, files or URL.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdfile">@file</a> Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdlink">@link</a> and <a href="http://doxygen.org/manual/commands.html#cmdendlink">@endlink</a> Describes a link to a file, class, or member.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdexample">@example</a> Describes source code examples.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdtodo">@todo</a> Describes a TODO item.</li>
-<li><a href="http://doxygen.org/manual/commands.html#cmdimage">@image</a> Describes an image.</li>
-</ul>
-
-
-<h2>Wrapping</h2>
-
-<p>We wrap long descriptions using 4 spaces on the next line.
-~~~
-@param uncompressed The input string that requires
- a very long description and an even longer
- description on this line as well.
-~~~</p>
-
-<h2>Outside Source Code</h2>
-
-<h3>Library and Component Overview Pages and User Guides</h3>
-
-<p>Substantial libraries, components, and subcomponents of the Mesos system such as
-stout, libprocess, master, slave, containerizer, allocator, and others
-should have an overview page in markdown format that explains their
-purpose, overall structure, and general use. This can even be a complete user guide.</p>
-
-<p>This page must be located in the top directory of the library/component and named “REAMDE.md”.</p>
-
-<p>The first line in such a document must be a section heading bearing the title which will appear in the generated Doxygen index.
-Example: “# Libprocess User Guide”</p>
-
-<h2>In Source Code</h2>
+<h2>Source Code Documentation Syntax</h2>
<p>Doxygen documentation needs only to be applied to source code parts that
constitute an interface for which we want to generate Mesos API documentation
@@ -149,6 +99,12 @@ enhanced by source code comments as appr
<p>We follow the <a href="http://en.wikipedia.org/wiki/Javadoc">Javadoc syntax</a> to mark comment blocks.
These have the general form:</p>
+<!-- NOTE: In order to show the comments as part of the code blocks in
+this we must use indentation instead of fenced code blocks (i.e.,
+~~~{.cpp}) because doxygen will remove all of the comments and just
+render the code. -->
+
+
<pre><code>/**
* Brief summary.
*
@@ -173,21 +129,144 @@ These have the general form:</p>
std::string compress(const std::string& uncompressed);
</code></pre>
-<h3>Constants and Variables</h3>
+<h3>Doxygen Tags</h3>
+
+<p>This is the allowed set of doxygen tags that can be used.</p>
+
+<ul>
+<li><a href="http://doxygen.org/manual/commands.html#cmdparam">\@param</a> Describes function parameters.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdreturn">\@return</a> Describes return values.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdsa">\@see</a> Describes a cross-reference to classes, functions, methods, variables, files or URL.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdfile">\@file</a> Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdlink">\@link</a> and <a href="http://doxygen.org/manual/commands.html#cmdendlink">\@endlink</a> Describes a link to a file, class, or member.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdexample">\@example</a> Describes source code examples.</li>
+<li><a href="http://doxygen.org/manual/commands.html#cmdtodo">\@todo</a> Describes a TODO item.</li>
+<li><p><a href="http://doxygen.org/manual/commands.html#cmdimage">\@image</a> Describes an image.</p></li>
+<li><p>When following these links be aware that the doxygen documentation is using another syntax in that \@param is explained as \param.</p></li>
+</ul>
+
+
+<h3>Wrapping</h3>
+
+<p>We wrap long descriptions using four spaces on the next line.</p>
+
+<pre><code>@param uncompressed The input string that requires
+ a very long description and an even longer
+ description on this line as well.
+</code></pre>
-<h3>Functions</h3>
+<h3>Constants and Variables</h3>
-<h3>Classes</h3>
+<p>Example:</p>
-<h4>Methods</h4>
+<pre><code>/**
+ * Prefix used to name Docker containers in order to distinguish
+ * those created by Mesos from those created manually.
+ */
+extern const std::string DOCKER_NAME_PREFIX;
+</code></pre>
<h4>Fields</h4>
-<h3>Templates</h3>
+<p>Example:</p>
+
+<pre><code>/**
+ * The parent side of the pipe for stdin.
+ * If the mode is not PIPE, None will be stored.
+ * @note: stdin is a macro on some systems, hence this name instead.
+ */
+Option<int> in;
+</code></pre>
+
+<h3>Functions and Methods</h3>
+
+<p>Example:</p>
-<h3>Macros</h3>
+<pre><code>/**
+ * Forks a subprocess and execs the specified 'path' with the
+ * specified 'argv', redirecting stdin, stdout, and stderr as
+ * specified by 'in', 'out', and 'err' respectively.
+ *
+ * If 'setup' is not None, runs the specified function after forking
+ * but before exec'ing. If the return value of 'setup' is non-zero
+ * then that gets returned in 'status()' and we will not exec.
+ *
+ * @param path Relative or absolute path in the filesytem to the
+ * executable.
+ * @param argv Argument vector to pass to exec.
+ * @param in Redirection specification for stdin.
+ * @param out Redirection specification for stdout.
+ * @param err Redirection specification for stderr.
+ * @param flags Flags to be stringified and appended to 'argv'.
+ * @param environment Environment variables to use for the new
+ * subprocess or if None (the default) then the new subprocess
+ * will inherit the environment of the current process.
+ * @param setup Function to be invoked after forking but before
+ * exec'ing. NOTE: Take extra care not to invoke any
+ * async unsafe code in the body of this function.
+ * @param clone Function to be invoked in order to fork/clone the
+ * subprocess.
+ * @return The subprocess or an error if one occurred.
+ */
+Try<Subprocess> subprocess(
+ const std::string& path,
+ std::vector<std::string> argv,
+ const Subprocess::IO& in = Subprocess::FD(STDIN_FILENO),
+ const Subprocess::IO& out = Subprocess::FD(STDOUT_FILENO),
+ const Subprocess::IO& err = Subprocess::FD(STDERR_FILENO),
+ const Option<flags::FlagsBase>& flags = None(),
+ const Option<std::map<std::string, std::string>>& environment = None(),
+ const Option<lambda::function<int()>>& setup = None(),
+ const Option<lambda::function<
+ pid_t(const lambda::function<int()>&)>>& clone = None());
+</code></pre>
+
+<h3>Classes and Structs</h3>
+
+<p>Example:</p>
+
+<pre><code>/**
+ * Represents a fork() exec()ed subprocess. Access is provided to the
+ * input / output of the process, as well as the exit status. The
+ * input / output file descriptors are only closed after:
+ * 1. The subprocess has terminated.
+ * 2. There are no longer any references to the associated
+ * Subprocess object.
+ */
+class Subprocess
+{
+public:
+</code></pre>
+
+<h2>Library and Component Overview Pages and Developer Guides</h2>
+
+<p>Substantial libraries, components, and subcomponents of the Mesos system such as
+stout, libprocess, master, slave, containerizer, allocator, and others
+should have an overview page in markdown format that explains their
+purpose, overall structure, and general use. This can even be a complete developer guide.</p>
+
+<p>This page must be located in the top directory of the library/component and named “REAMDE.md”.</p>
+
+<p>The first line in such a document must be a section heading bearing the title which will appear in the generated Doxygen index.
+Example: “# Libprocess Developer Guide”</p>
+
+<h3>Example Code</h3>
+
+<p>C++ code examples should be enclosed by ‘~~~{.cpp}’.</p>
+
+<p>Example:</p>
+
+<pre><code class="{.cpp}">int main(int argc, char** argv)
+{
+ ...
+}
+</code></pre>
+
+<p><strong>NOTE</strong>: Because of shortcomings of Doxygen’s markdown parser we currently use indentation for wrapping all non C++ code blocks.</p>
+
+<h2>Building Doxygen Documentation</h2>
-<h3>Global declarations outside classes</h3>
+<p>As of right now, the Doxygen documentation should be built from the <em>build</em> subdirectory using <em>doxygen ../Doxyfile</em> . The documentation will then be generated into the <em>./doxygen</em> subdirectory.</p>
</div>
</div>
Added: mesos/site/publish/documentation/mesos-markdown-style-guide/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-markdown-style-guide/index.html?rev=1688707&view=auto
==============================================================================
--- mesos/site/publish/documentation/mesos-markdown-style-guide/index.html (added)
+++ mesos/site/publish/documentation/mesos-markdown-style-guide/index.html Wed Jul 1 18:55:31 2015
@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title></title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+ <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
+ <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
+
+ <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />
+
+
+
+ <!-- Google Analytics Magic -->
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-20226872-1']);
+ _gaq.push(['_setDomainName', 'apache.org']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+ </head>
+ <body>
+ <!-- magical breadcrumbs -->
+ <div class="topnav">
+ <ul class="breadcrumb">
+ <li>
+ <div class="dropdown">
+ <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
+ <li><a href="http://www.apache.org">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </div>
+ </li>
+ <li><a href="http://mesos.apache.org">Apache Mesos</a></li>
+
+
+ <li><a href="/documentation
+/">Documentation
+</a></li>
+
+
+ </ul><!-- /breadcrumb -->
+ </div>
+
+ <!-- navbar excitement -->
+ <div class="navbar navbar-static-top" role="navigation">
+ <div class="navbar-inner">
+ <div class="container">
+ <a href="/" class="logo"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo" /></a>
+ <div class="nav-collapse">
+ <ul class="nav nav-pills navbar-right">
+ <li><a href="/gettingstarted/">Getting Started</a></li>
+ <li><a href="/documentation/latest/">Documentation</a></li>
+ <li><a href="/downloads/">Downloads</a></li>
+ <li><a href="/community/">Community</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div><!-- /.navbar -->
+
+ <div class="container">
+
+ <div class="row-fluid">
+ <div class="col-md-4">
+ <h4>If you're new to Mesos</h4>
+ <p>See the <a href="/gettingstarted/">getting started</a> page for more information about downloading, building, and deploying Mesos.</p>
+
+ <h4>If you'd like to get involved or you're looking for support</h4>
+ <p>See our <a href="/community/">community</a> page for more details.</p>
+ </div>
+ <div class="col-md-8">
+ <h1>Mesos Markdown Style Guide</h1>
+
+<p>This guide introduces a consistent documentation style to be used across the entire non-code documentation.
+User guides and non-code technical documentation are stored in markdown files in the <code>docs/</code> folder. These files get rendered for the <a href="http://mesos.apache.org/documentation/latest/">online documentation</a>.</p>
+
+<p><strong>NOTE:</strong> As of right now this is work in progress and the existing documentation might not yet comply to this style.</p>
+
+<h2>What to document?</h2>
+
+<p>Any new substantial feature should be documented in its own markdown file.
+If the link between source code and documentation is not obvious, consider inserting a short code comment stating that there is non-code documentation that needs to be kept in sync and indicating where it is located.</p>
+
+<h2>Keep documentation and style-guides in sync with code.</h2>
+
+<p>When changing code consider whether you need to update the documentation.
+This is especially relevant when introducing new or updating existing command line flags.
+These should be reflected in <code>configuration.md</code>!</p>
+
+<h2>Code Examples</h2>
+
+<p>Code examples should be specified as follows:</p>
+
+<pre><code>~~~{.cpp}
+int main(int argc, char** argv)
+{
+ ....
+}
+~~~
+</code></pre>
+
+<p><strong>NOTE:</strong> Because of shortcomings of Doxygen’s markdown parser we currently use indentation for wrapping all non C++ code blocks.</p>
+
+<h2>Notes/Emphasis</h2>
+
+<p>Notes are used to highlight important parts of the text and should be specified as follows.</p>
+
+<pre><code class="{.txt}">**NOTE:** Short note.
+Continued longer note.
+</code></pre>
+
+<p>We use single backticks to highlight individual words in a sentence such as certain identifiers:</p>
+
+<pre><code class="{.txt}">Use the default `HierarchicalDRF` allocator....
+</code></pre>
+
+<h2>Commands</h2>
+
+<p>We use single backticks to highlight sample commands as follows:</p>
+
+<pre><code class="{.txt}">`mesos-master --help`
+</code></pre>
+
+<h2>Files/Path</h2>
+
+<p>Files and path references should be specified as follows:</p>
+
+<pre><code class="{.text}">Remember you can also use the `file:///path/to/file` or `/path/to/file`
+</code></pre>
+
+<h2>Tables</h2>
+
+<p>In order to avoid problems with markdown formatting we should specify tables in html directly:</p>
+
+<p>~~~{.html}</p>
+
+<table class="table table-striped">
+ <thead>
+ <tr>
+ <th width="30%">
+ Flag
+ </th>
+ <th>
+ Explanation
+ </th>
+ </thead>
+ <tr>
+ <td>
+ --ip=VALUE
+ </td>
+ <td>
+ IP address to listen on
+ </td>
+ </tr>
+ <tr>
+ <td>
+ --[no-]help
+ </td>
+ <td>
+ Prints this help message (default: false)
+
+ </td>
+ </tr>
+</table>
+
+
+<pre><code>
+
+## Indendation and Whitespace
+
+We use no extra indentation in markdown files.
+We have one new line after section headings and two blank lines
+in between sections.
+</code></pre>
+
+<p>… end of previous section.</p>
+
+<h2>New Section</h2>
+
+<p>Beginning of new section ….
+~~~</p>
+
+ </div>
+</div>
+
+
+ <hr>
+
+ <!-- footer -->
+ <div class="footer">
+ <p>© 2012-2014 <a href="http://apache.org">The Apache Software Foundation</a>.
+ Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.<p>
+ </div><!-- /footer -->
+
+ </div> <!-- /container -->
+
+ <!-- JS -->
+ <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
+ </body>
+</html>
\ No newline at end of file
Added: mesos/site/publish/documentation/mesos-ssl/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-ssl/index.html?rev=1688707&view=auto
==============================================================================
--- mesos/site/publish/documentation/mesos-ssl/index.html (added)
+++ mesos/site/publish/documentation/mesos-ssl/index.html Wed Jul 1 18:55:31 2015
@@ -0,0 +1,210 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title></title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+ <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
+ <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
+
+ <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />
+
+
+
+ <!-- Google Analytics Magic -->
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-20226872-1']);
+ _gaq.push(['_setDomainName', 'apache.org']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+ </head>
+ <body>
+ <!-- magical breadcrumbs -->
+ <div class="topnav">
+ <ul class="breadcrumb">
+ <li>
+ <div class="dropdown">
+ <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
+ <li><a href="http://www.apache.org">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </div>
+ </li>
+ <li><a href="http://mesos.apache.org">Apache Mesos</a></li>
+
+
+ <li><a href="/documentation
+/">Documentation
+</a></li>
+
+
+ </ul><!-- /breadcrumb -->
+ </div>
+
+ <!-- navbar excitement -->
+ <div class="navbar navbar-static-top" role="navigation">
+ <div class="navbar-inner">
+ <div class="container">
+ <a href="/" class="logo"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo" /></a>
+ <div class="nav-collapse">
+ <ul class="nav nav-pills navbar-right">
+ <li><a href="/gettingstarted/">Getting Started</a></li>
+ <li><a href="/documentation/latest/">Documentation</a></li>
+ <li><a href="/downloads/">Downloads</a></li>
+ <li><a href="/community/">Community</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div><!-- /.navbar -->
+
+ <div class="container">
+
+ <div class="row-fluid">
+ <div class="col-md-4">
+ <h4>If you're new to Mesos</h4>
+ <p>See the <a href="/gettingstarted/">getting started</a> page for more information about downloading, building, and deploying Mesos.</p>
+
+ <h4>If you'd like to get involved or you're looking for support</h4>
+ <p>See our <a href="/community/">community</a> page for more details.</p>
+ </div>
+ <div class="col-md-8">
+ <h1>Configuration</h1>
+
+<p>There is currently only one implementation of the <a href="https://github.com/apache/mesos/blob/master/3rdparty/libprocess/include/process/socket.hpp">libprocess socket interface</a> that supports SSL. This implementation uses <a href="https://github.com/libevent/libevent">libevent</a>. Specifically it relies on the <code>libevent-openssl</code> library that wraps <code>openssl</code>.</p>
+
+<p>After building <code>Mesos 0.23.0</code> from source, assuming you have installed the required <a href="#Dependencies">Dependencies</a>, you can modify your configure line to enable SSL as follows:</p>
+
+<pre><code>../configure --enable-libevent --enable-ssl
+</code></pre>
+
+<h1>Running</h1>
+
+<p>Once you have successfully built and installed your new binaries, here are the environment variables that are applicable to the <code>Master</code>, <code>Slave</code>, <code>Framework Scheduler/Executor</code>, or any <code>libprocess process</code>:</p>
+
+<h5>SSL_ENABLED=(false|0,true|1) [default=false|0]</h5>
+
+<p>Turn on or off SSL. When it is turned off it is the equivalent of default mesos with libevent as the backing for events. All sockets default to the non-SSL implementation. When it is turned on, the default configuration for sockets is SSL. This means outgoing connections will use SSL, and incoming connections will be expected to speak SSL as well. None of the below flags are relevant if SSL is not enabled.</p>
+
+<h5>SSL_SUPPORT_DOWNGRADE=(false|0,true|1) [default=false|0]</h5>
+
+<p>Control whether or not non-SSL connections can be established. If this is enabled <strong>on the accepting side</strong>, then the accepting side will downgrade to a non-SSL socket if the connecting side is attempting to communicate via non-SSL. (e.g. http). See <a href="#Upgrading">Upgrading Your Cluster</a> for more details.</p>
+
+<h5>SSL_CERT_FILE=(path to certificate)</h5>
+
+<p>The location of the certificate this binary will present.</p>
+
+<h5>SSL_KEY_FILE=(path to key)</h5>
+
+<p>The location of the private key used by OpenSSL.</p>
+
+<h5>SSL_VERIFY_CERT=(false|0,true|1) [default=false|0]</h5>
+
+<p>Control whether certificates are verified when presented. If this is false, even when a certificate is presented, it will not be verified. When <code>SSL_REQUIRE_CERT</code> is true, <code>SSL_VERIFY_CERT</code> is overridden and all certificates will be verified <em>and</em> required.</p>
+
+<h5>SSL_REQUIRE_CERT=(false|0,true|1) [default=false|0]</h5>
+
+<p>Enforce that certificates must be presented by connecting clients. This means all connections (including tools hitting endpoints) must present valid certificates in order to establish a connection.</p>
+
+<h5>SSL_VERIFY_DEPTH=(4) [default=4]</h5>
+
+<p>The maximum depth used to verify certificates. The default is 4. See the OpenSSL documentation or contact your system administrator to learn why you may want to change this.</p>
+
+<h5>SSL_CA_DIR=(path to CA directory)</h5>
+
+<p>The directory used to find the certificate authority / authorities. You can specify <code>SSL_CA_DIR</code> or <code>SSL_CA_FILE</code> depending on how you want to restrict your certificate authorization.</p>
+
+<h5>SSL_CA_FILE=(path to CA file)</h5>
+
+<p>The file used to find the certificate authority. You can specify <code>SSL_CA_DIR</code> or <code>SSL_CA_FILE</code> depending on how you want to restrict your certificate authorization.</p>
+
+<h5>SSL_CIPHERS=(accepted ciphers separated by ‘:’) [default=AES128-SHA:AES256-SHA:RC4-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA]</h5>
+
+<p>A list of <code>:</code>-separated ciphers. Use these if you want to restrict or open up the accepted ciphers for OpenSSL. Read the OpenSSL documentation or contact your system administrators to see whether you want to override the default values.</p>
+
+<h5>SSL_ENABLE_SSL_V2=(false|0,true|1) [default=false|0]</h5>
+
+<h5>SSL_ENABLE_SSL_V3=(false|0,true|1) [default=false|0]</h5>
+
+<h5>SSL_ENABLE_TLS_V1_0=(false|0,true|1) [default=false|0]</h5>
+
+<h5>SSL_ENABLE_TLS_V1_1=(false|0,true|1) [default=false|0]</h5>
+
+<h5>SSL_ENABLE_TLS_V1_2=(false|0,true|1) [default=true|1]</h5>
+
+<p>The above switches enable / disable the specified protocols. By default only TLS V1.2 is enabled. The mentality here is to restrict security by default, and force users to open it up explicitly. Many older version of the protocols have known vulnerabilities, so only enable these if you understand the risks fully.</p>
+
+<h1><a name="Dependencies"></a>Dependencies</h1>
+
+<h3>libevent</h3>
+
+<p>We require the OpenSSL support from libevent. The suggested version of libevent is <a href="https://github.com/libevent/libevent/releases/tag/release-2.0.22-stable"><code>2.0.22-stable</code></a>. As new releases come out we will try to maintain compatibility.
+~~~
+// For example, on OSX:
+brew install libevent
+~~~</p>
+
+<h3>OpenSSL</h3>
+
+<p>We require <a href="https://github.com/openssl/openssl">OpenSSL</a>. There are multiple branches of OpenSSL that are being maintained by the community. Since security requires being vigilant, we recommend reading the release notes for the current releases of OpenSSL and deciding on a version within your organization based on your security needs. Mesos is not too deeply dependent on specific OpenSSL versions, so there is room for you to make security decisions as an organization.
+Please ensure the <code>event2</code> and <code>openssl</code> headers are available for building mesos.
+~~~
+// For example, on OSX:
+brew install openssl
+~~~</p>
+
+<h1><a name="Upgrading"></a>Upgrading Your Cluster</h1>
+
+<p><em>There is no SSL specific requirement for upgrading different components in a specific order.</em></p>
+
+<p>The recommended strategy is to restart all your components to enable SSL with downgrades support enabled. Once all components have SSL enabled, then do a second restart of all your components to disable downgrades. This strategy will allow each component to be restarted independently at your own convenience with no time restrictions. It will also allow you to try SSL in a subset of your cluster. <em>Please note:</em> While different components in your cluster are serving SSL vs non-SSL traffic, any relative links in the WebUI may be broken. Please see the <a href="#WebUI">WebUI</a> section for details. Here are sample commands for upgrading your cluster:
+~~~
+// Restart each component with downgrade support (master, slave, framework):
+SSL_ENABLED=true SSL_SUPPORT_DOWNGRADE=true SSL_KEY_FILE=<path-to-your-private-key> SSL_CERT_FILE=<path-to-your-certificate> <Any other SSL_* environment variables you may choose> <your-component (e.g. bin/master.sh)> <your-flags></p>
+
+<p>// Restart each component WITHOUT downgrade support (master, slave, framework):
+SSL_ENABLED=true SSL_SUPPORT_DOWNGRADE=false SSL_KEY_FILE=<path-to-your-private-key> SSL_CERT_FILE=<path-to-your-certificate> <Any other SSL_* environment variables you may choose> <your-component (e.g. bin/master.sh)> <your-flags>
+~~~
+The end state is a cluster that is only communicating with SSL.</p>
+
+<p><em>Please note:</em> Any tools you may use that communicate with your components must be able to talk SSL, or they will be denied. You may choose to maintain <code>SSL_SUPPORT_DOWNGRADE=true</code> for some time as you upgrade your internal tooling. The advantage of <code>SSL_SUPPORT_DOWNGRADE=true</code> is that all components that speak SSL will do so, while other components may still communicate over insecure channels.</p>
+
+<h1><a name="WebUI"></a>WebUI</h1>
+
+<p>The default Mesos WebUI uses relative links. Some of these links transition between endpoints served by the master and slaves. The WebUI currently does not have enough information to change the ‘http’ vs ‘https’ links based on whether the target endpoint is currently being served by an SSL-enabled binary. This may cause certain links in the WebUI to be broken when a cluster is in a transition state between SSL and non-SSL. Any tools that hit these endpoints will still be able to access them as long as they hit the endpoint using the right protocol, or the SSL_SUPPORT_DOWNGRADE option is set to true.</p>
+
+<h3>Certificates</h3>
+
+<p>Most browsers have built in protection that guard transitions between pages served using different certificates. For this reason you may choose to serve both the master and slave endpoints using a common certificate that covers multiple hostnames. If you do not do this, certain links, such as those to slave sandboxes, may seem broken as the browser treats the transition between differing certificates transition as unsafe.</p>
+
+ </div>
+</div>
+
+
+ <hr>
+
+ <!-- footer -->
+ <div class="footer">
+ <p>© 2012-2014 <a href="http://apache.org">The Apache Software Foundation</a>.
+ Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.<p>
+ </div><!-- /footer -->
+
+ </div> <!-- /container -->
+
+ <!-- JS -->
+ <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
+ </body>
+</html>
\ No newline at end of file
Modified: mesos/site/publish/documentation/mesos-testing-patterns/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/mesos-testing-patterns/index.html?rev=1688707&r1=1688706&r2=1688707&view=diff
==============================================================================
--- mesos/site/publish/documentation/mesos-testing-patterns/index.html (original)
+++ mesos/site/publish/documentation/mesos-testing-patterns/index.html Wed Jul 1 18:55:31 2015
@@ -91,50 +91,50 @@
<p>Every message enqueued in a libprocess process' (or actor’s, to avoid ambiguity with OS processes) mailbox is processed by <code>ProcessManager</code> (right now there is a single instance of <code>ProcessManager</code> per OS process, but this may change in the future). <code>ProcessManager</code> fetches actors from the runnable actors list and services all events from the actor’s mailbox. Using <code>Clock::settle()</code> call we can block the calling thread until <code>ProcessManager</code> empties mailboxes of all actors. Here is the example of this pattern:</p>
-<pre><code class="{.cpp}"> // As Master::killTask isn't doing anything, we shouldn't get a status update.
- EXPECT_CALL(sched, statusUpdate(&driver, _))
- .Times(0);
+<pre><code class="{.cpp}">// As Master::killTask isn't doing anything, we shouldn't get a status update.
+EXPECT_CALL(sched, statusUpdate(&driver, _))
+ .Times(0);
- // Set expectation that Master receives killTask message.
- Future<KillTaskMessage> killTaskMessage =
- FUTURE_PROTOBUF(KillTaskMessage(), _, master.get());
+// Set expectation that Master receives killTask message.
+Future<KillTaskMessage> killTaskMessage =
+ FUTURE_PROTOBUF(KillTaskMessage(), _, master.get());
- // Attempt to kill unknown task while slave is transitioning.
- TaskID unknownTaskId;
- unknownTaskId.set_value("2");
+// Attempt to kill unknown task while slave is transitioning.
+TaskID unknownTaskId;
+unknownTaskId.set_value("2");
- // Stop the clock.
- Clock::pause();
+// Stop the clock.
+Clock::pause();
- // Initiate an action.
- driver.killTask(unknownTaskId);
+// Initiate an action.
+driver.killTask(unknownTaskId);
- // Make sure the event associated with the action has been queued.
- AWAIT_READY(killTaskMessage);
+// Make sure the event associated with the action has been queued.
+AWAIT_READY(killTaskMessage);
- // Wait for all messages to be dispatched and processed completely to satisfy
- // the expectation that we didn't receive a status update.
- Clock::settle();
+// Wait for all messages to be dispatched and processed completely to satisfy
+// the expectation that we didn't receive a status update.
+Clock::settle();
- Clock::resume();
+Clock::resume();
</code></pre>
<h2>Intercepting a message sent to a different OS process</h2>
<p>Intercepting messages sent between libprocess processes (let’s call them actors to avoid ambiguity with OS processes) that live in the same OS process is easy, e.g.:</p>
-<pre><code class="{.cpp}"> Future<SlaveReregisteredMessage> slaveReregisteredMessage =
- FUTURE_PROTOBUF(SlaveReregisteredMessage(), _, _);
- ...
- AWAIT_READY(slaveReregisteredMessage);
+<pre><code class="{.cpp}">Future<SlaveReregisteredMessage> slaveReregisteredMessage =
+ FUTURE_PROTOBUF(SlaveReregisteredMessage(), _, _);
+...
+AWAIT_READY(slaveReregisteredMessage);
</code></pre>
<p>However, this won’t work if we want to intercept a message sent to an actor (technically a <code>UPID</code>) that lives in another OS process. For example, <code>CommandExecutor</code> spawned by a slave will live in a separate OS process, though master and slave instances live in the same OS process together with our test (see <code>mesos/src/tests/cluster.hpp</code>). The wait in this code will fail:</p>
-<pre><code class="{.cpp}"> Future<ExecutorRegisteredMessage> executorRegisteredMessage =
- FUTURE_PROTOBUF(ExecutorRegisteredMessage(), _, _);
- ...
- AWAIT_READY(executorRegisteredMessage);
+<pre><code class="{.cpp}">Future<ExecutorRegisteredMessage> executorRegisteredMessage =
+ FUTURE_PROTOBUF(ExecutorRegisteredMessage(), _, _);
+...
+AWAIT_READY(executorRegisteredMessage);
</code></pre>
<h3>Why messages sent outside the OS process are not intercepted?</h3>
@@ -149,13 +149,13 @@
<p>For the aforementioned example, instead of intercepting <code>ExecutorRegisteredMessage</code>, we can intercept <code>RegisterExecutorMessage</code> and wait until its processed, which includes sending <code>ExecutorRegisteredMessage</code> (see <code>Slave::registerExecutor()</code>):</p>
-<pre><code class="{.cpp}"> Future<RegisterExecutorMessage> registerExecutorMessage =
- FUTURE_PROTOBUF(RegisterExecutorMessage(), _, _);
- ...
- AWAIT_READY(registerExecutorMessage);
- Clock::pause();
- Clock::settle();
- Clock::resume();
+<pre><code class="{.cpp}">Future<RegisterExecutorMessage> registerExecutorMessage =
+ FUTURE_PROTOBUF(RegisterExecutorMessage(), _, _);
+...
+AWAIT_READY(registerExecutorMessage);
+Clock::pause();
+Clock::settle();
+Clock::resume();
</code></pre>
</div>
Modified: mesos/site/publish/documentation/modules/index.html
URL: http://svn.apache.org/viewvc/mesos/site/publish/documentation/modules/index.html?rev=1688707&r1=1688706&r2=1688707&view=diff
==============================================================================
--- mesos/site/publish/documentation/modules/index.html (original)
+++ mesos/site/publish/documentation/modules/index.html Wed Jul 1 18:55:31 2015
@@ -127,51 +127,51 @@ of the form ‘file:///path/to/file&
<li><p>Load a library <code>libfoo.so</code> with two modules <code>org_apache_mesos_bar</code> and
<code>org_apache_mesos_baz</code>.</p>
-<pre><code>{
- "libraries": [
- {
- "file": "/path/to/libfoo.so",
- "modules": [
- {
- "name": "org_apache_mesos_bar",
- },
- {
- "name": "org_apache_mesos_baz"
- }
- ]
- }
- ]
-}
+<pre><code> {
+ "libraries": [
+ {
+ "file": "/path/to/libfoo.so",
+ "modules": [
+ {
+ "name": "org_apache_mesos_bar",
+ },
+ {
+ "name": "org_apache_mesos_baz"
+ }
+ ]
+ }
+ ]
+ }
</code></pre></li>
<li><p>Load the module <code>org_apache_mesos_bar</code> from the library <code>foo</code> and pass
the command-line argument <code>X</code> with value <code>Y</code> (module <code>org_apache_mesos_baz</code>
is loaded without any command-line parameters):</p>
-<pre><code>{
- "libraries": [
- {
- "name": "foo",
- "modules": [
- {
- "name": "org_apache_mesos_bar"
- "parameters": [
- {
- "key": "X",
- "value": "Y",
- }
- ]
- },
- {
- "name": "org_apache_mesos_bar"
- }
- ]
- }
- ]
-}
+<pre><code> {
+ "libraries": [
+ {
+ "name": "foo",
+ "modules": [
+ {
+ "name": "org_apache_mesos_bar"
+ "parameters": [
+ {
+ "key": "X",
+ "value": "Y",
+ }
+ ]
+ },
+ {
+ "name": "org_apache_mesos_bar"
+ }
+ ]
+ }
+ ]
+ }
</code></pre></li>
<li><p>Specifying modules inline:</p>
-<pre><code>--modules='{"libraries":[{"file":"/path/to/libfoo.so", "modules":[{"name":"org_apache_mesos_bar"}]}]}'
+<pre><code> --modules='{"libraries":[{"file":"/path/to/libfoo.so", "modules":[{"name":"org_apache_mesos_bar"}]}]}'
</code></pre></li>
</ol>
@@ -305,71 +305,71 @@ for GPGPU hardware, networking, etc.</p>
<p>The following snippet describes the implementation of a module named
“org_apache_mesos_bar” of “TestModule” kind:</p>
-<pre><code> #include <iostream>
- #include "test_module.hpp"
+<pre><code class="{.cpp}">#include <iostream>
+#include "test_module.hpp"
- class TestModuleImpl : public TestModule
+class TestModuleImpl : public TestModule
+{
+public:
+ TestModuleImpl()
{
- public:
- TestModuleImpl()
- {
- std::cout << "HelloWorld!" << std::endl;
- }
-
- virtual int foo(char a, long b)
- {
- return a + b;
- }
-
- virtual int bar(float a, double b)
- {
- return a * b;
- }
- };
+ std::cout << "HelloWorld!" << std::endl;
+ }
- static TestModule* create()
+ virtual int foo(char a, long b)
{
- return new TestModule();
+ return a + b;
}
- static bool compatible()
+ virtual int bar(float a, double b)
{
- return true;
+ return a * b;
}
+};
+
+static TestModule* create()
+{
+ return new TestModule();
+}
- // Declares a module named 'org_apache_mesos_TestModule' of
- // 'TestModule' kind.
- // Mesos core binds the module instance pointer as needed.
- // The compatible() hook is provided by the module for compatibility checks.
- // The create() hook returns an object of type 'TestModule'.
- mesos::modules::Module<TestModule> org_apache_mesos_TestModule(
- MESOS_MODULE_API_VERSION,
- MESOS_VERSION,
- "Apache Mesos",
- "modules@mesos.apache.org",
- "This is a test module.",
- compatible,
- create);
+static bool compatible()
+{
+ return true;
+}
+
+// Declares a module named 'org_apache_mesos_TestModule' of
+// 'TestModule' kind.
+// Mesos core binds the module instance pointer as needed.
+// The compatible() hook is provided by the module for compatibility checks.
+// The create() hook returns an object of type 'TestModule'.
+mesos::modules::Module<TestModule> org_apache_mesos_TestModule(
+ MESOS_MODULE_API_VERSION,
+ MESOS_VERSION,
+ "Apache Mesos",
+ "modules@mesos.apache.org",
+ "This is a test module.",
+ compatible,
+ create);
</code></pre>
<h3>Building a module</h3>
<p> The following assumes that Mesos is installed in the standard location, i.e.
- the Mesos dynamic library and header files are available.
-<code>
- g++ -lmesos -fpic -o test_module.o test_module.cpp
- $ gcc -shared -o libtest_module.so test_module.o
-</code></p>
+ the Mesos dynamic library and header files are available.</p>
+
+<pre><code>g++ -lmesos -fpic -o test_module.o test_module.cpp
+$ gcc -shared -o libtest_module.so test_module.o
+</code></pre>
<h3>Testing a modules</h3>
<p>Apart from testing the module by hand with explicit use of –modules flag, one
can run the entire mesos test suite with the given module. For example, the
following command will run the mesos test suite with the
-<code>org_apache_mesos_TestCpuIsolator</code> module selected for isolation:
-<code>
-./bin/mesos-tests.sh --modules="/home/kapil/mesos/isolator-module/modules.json" --isolation="org_apache_mesos_TestCpuIsolator"
-</code></p>
+<code>org_apache_mesos_TestCpuIsolator</code> module selected for isolation:</p>
+
+<pre><code>./bin/mesos-tests.sh --modules="/home/kapil/mesos/isolator-module/modules.json" --isolation="org_apache_mesos_TestCpuIsolator"
+</code></pre>
<h3>Module naming convention</h3>
@@ -450,7 +450,6 @@ must exist between the various versions:
<tr>
<td>0.29.0 </td> <td> 0.21.0 </td> <td> 0.18.0 </td> <td> NO </td> <td> Module/Library older than the kind version supported by Mesos. </td>
-<tr>
</tr>
<tr>
@@ -479,54 +478,50 @@ must exist between the various versions:
<h3>JSON Schema:</h3>
-<pre><code> {
- "type":"object",
- "required":false,
- "properties":{
- "libraries": {
- "type":"array",
+<pre><code>{
+ "type":"object",
+ "required":false,
+ "properties":{
+ "libraries":{
+ "type":"array",
+ "required":false,
+ "items":{
+ "type":"object",
"required":false,
- "items":
- {
- "type":"object",
- "required":false,
- "properties":{
- "file": {
- "type":"string",
- "required":false
- },
- "name": {
- "type":"string",
- "required":false
- },
- "modules": {
- "type":"array",
+ "properties":{
+ "file":{
+ "type":"string",
+ "required":false
+ },
+ "name":{
+ "type":"string",
+ "required":false
+ },
+ "modules":{
+ "type":"array",
+ "required":false,
+ "items":{
+ "type":"object",
"required":false,
- "items":
- {
- "type":"object",
- "required":false,
- "properties":{
- "name": {
- "type":"string",
- "required":true
- },
- "parameters": {
- "type":"array",
+ "properties":{
+ "name":{
+ "type":"string",
+ "required":true
+ },
+ "parameters":{
+ "type":"array",
+ "required":false,
+ "items":{
+ "type":"object",
"required":false,
- "items":
- {
- "type":"object",
- "required":false,
- "properties":{
- "key": {
- "type":"string",
- "required":true
- },
- "value": {
- "type":"string",
- "required":true
- }
+ "properties":{
+ "key":{
+ "type":"string",
+ "required":true
+ },
+ "value":{
+ "type":"string",
+ "required":true
}
}
}
@@ -538,6 +533,7 @@ must exist between the various versions:
}
}
}
+}
</code></pre>
</div>