Modified: mesos/site/source/documentation/latest.html.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest.html.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest.html.md (original) +++ mesos/site/source/documentation/latest.html.md Wed Jul 1 18:55:31 2015 @@ -20,6 +20,7 @@ layout: documentation * [Logging and Debugging](/documentation/latest/logging-and-debugging/) for viewing Mesos and framework logs. * [High Availability](/documentation/latest/high-availability/) for running multiple masters simultaneously. * [Operational Guide](/documentation/latest/operational-guide/) +* [Monitoring](/documentation/latest/monitoring/) * [Network Monitoring](/documentation/latest/network-monitoring/) * [Slave Recovery](/documentation/latest/slave-recovery/) for doing seamless upgrades. * [Tools](/documentation/latest/tools/) for setting up and running a Mesos cluster. @@ -50,8 +51,10 @@ layout: documentation * [Committing](/documentation/latest/committing/) guidelines for committing changes. * [Committers and Maintainers](/documentation/latest/committers/) a listing of project committers and component maintainers; useful when seeking feedback. * [Doxygen](/api/latest/c++/) documents the internal Mesos APIs. -* [C++ Style Guide](/documentation/latest/mesos-c++-style-guide/) -* [Doxygen Style Guide](/documentation/latest/mesos-doxygen-style-guide/) +* [Documentation Guide](/documentation/latest/mesos-documentation-guide/) + * [C++ Style Guide](/documentation/latest/mesos-c++-style-guide/) + * [Doxygen Style Guide](/documentation/latest/mesos-doxygen-style-guide/) + * [Markdown Style Guide](/documentation/latest/mesos-markdown-style-guide/) * [Development Roadmap](/documentation/latest/mesos-roadmap/) * [Release Guide](/documentation/latest/release-guide/)
Modified: mesos/site/source/documentation/latest/allocation-module.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/allocation-module.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/allocation-module.md (original) +++ mesos/site/source/documentation/latest/allocation-module.md Wed Jul 1 18:55:31 2015 @@ -33,7 +33,7 @@ Once a custom allocator has been written An allocator module is a factory function and a module description, as defined in `mesos/module/allocator.hpp`. Assuming the allocation logic is implemented by the `ExternalAllocator` class declared in `external_allocator.hpp`, the following snippet describes the implementation of an allocator module named `ExternalAllocatorModule`: -``` +~~~{.cpp} #include <mesos/master/allocator.hpp> #include <mesos/module/allocator.hpp> #include <stout/try.hpp> @@ -63,6 +63,6 @@ mesos::modules::Module<Allocator> Extern "External Allocator module.", NULL, createExternalAllocator); -``` +~~~ Refer to the [Mesos Modules documentation](http://mesos.apache.org/documentation/latest/modules/) for instructions how to compile and load a module in Mesos master. Modified: mesos/site/source/documentation/latest/app-framework-development-guide.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/app-framework-development-guide.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/app-framework-development-guide.md (original) +++ mesos/site/source/documentation/latest/app-framework-development-guide.md Wed Jul 1 18:55:31 2015 @@ -6,127 +6,126 @@ layout: documentation In this document we refer to Mesos applications as "frameworks". -See one of the example framework schedulers in `MESOS_HOME/src/examples/` to get an idea of what a Mesos framework scheduler and executor in the language of your choice looks like. +See one of the example framework schedulers in `MESOS_HOME/src/examples/` to get an idea of what a Mesos framework scheduler and executor in the language of your choice looks like. [RENDLER](https://github.com/mesosphere/RENDLER) provides example framework implementations in C++, Go, Haskell, Java, Python and Scala. ## Create your Framework Scheduler -You can write a framework scheduler in C, C++, Java/Scala, or Python. Your framework scheduler should inherit from the `Scheduler` class (see API below). Your scheduler should create a SchedulerDriver (which will mediate communication between your scheduler and the Mesos master) and then call `SchedulerDriver.run()` +You can write a framework scheduler in C, C++, Java/Scala, or Python. Your framework scheduler should inherit from the `Scheduler` class (see API below). Your scheduler should create a SchedulerDriver (which will mediate communication between your scheduler and the Mesos master) and then call `SchedulerDriver.run()`. ### Scheduler API Declared in `MESOS_HOME/include/mesos/scheduler.hpp` - -``` - /** - * Empty virtual destructor (necessary to instantiate subclasses). - */ - virtual ~Scheduler() {} - - /** - * Invoked when the scheduler successfully registers with a Mesos - * master. A unique ID (generated by the master) used for - * distinguishing this framework from others and MasterInfo - * with the ip and port of the current master are provided as arguments. - */ - virtual void registered(SchedulerDriver* driver, - const FrameworkID& frameworkId, +~~~{.cpp} +/* + * Empty virtual destructor (necessary to instantiate subclasses). + */ +virtual ~Scheduler() {} + +/* + * Invoked when the scheduler successfully registers with a Mesos + * master. A unique ID (generated by the master) used for + * distinguishing this framework from others and MasterInfo + * with the ip and port of the current master are provided as arguments. + */ +virtual void registered(SchedulerDriver* driver, + const FrameworkID& frameworkId, + const MasterInfo& masterInfo) = 0; + +/* + * Invoked when the scheduler re-registers with a newly elected Mesos master. + * This is only called when the scheduler has previously been registered. + * MasterInfo containing the updated information about the elected master + * is provided as an argument. + */ +virtual void reregistered(SchedulerDriver* driver, const MasterInfo& masterInfo) = 0; - /** - * Invoked when the scheduler re-registers with a newly elected Mesos master. - * This is only called when the scheduler has previously been registered. - * MasterInfo containing the updated information about the elected master - * is provided as an argument. - */ - virtual void reregistered(SchedulerDriver* driver, - const MasterInfo& masterInfo) = 0; - - /** - * Invoked when the scheduler becomes "disconnected" from the master - * (e.g., the master fails and another is taking over). - */ - virtual void disconnected(SchedulerDriver* driver) = 0; - - /** - * Invoked when resources have been offered to this framework. A - * single offer will only contain resources from a single slave. - * Resources associated with an offer will not be re-offered to - * _this_ framework until either (a) this framework has rejected - * those resources (see SchedulerDriver::launchTasks) or (b) those - * resources have been rescinded (see Scheduler::offerRescinded). - * Note that resources may be concurrently offered to more than one - * framework at a time (depending on the allocator being used). In - * that case, the first framework to launch tasks using those - * resources will be able to use them while the other frameworks - * will have those resources rescinded (or if a framework has - * already launched tasks with those resources then those tasks will - * fail with a TASK_LOST status and a message saying as much). - */ - virtual void resourceOffers(SchedulerDriver* driver, - const std::vector<Offer>& offers) = 0; - - /** - * Invoked when an offer is no longer valid (e.g., the slave was - * lost or another framework used resources in the offer). If for - * whatever reason an offer is never rescinded (e.g., dropped - * message, failing over framework, etc.), a framwork that attempts - * to launch tasks using an invalid offer will receive TASK_LOST - * status updats for those tasks (see Scheduler::resourceOffers). - */ - virtual void offerRescinded(SchedulerDriver* driver, - const OfferID& offerId) = 0; - - /** - * Invoked when the status of a task has changed (e.g., a slave is - * lost and so the task is lost, a task finishes and an executor - * sends a status update saying so, etc). If implicit - * acknowledgements are being used, then returning from this - * callback _acknowledges_ receipt of this status update! If for - * whatever reason the scheduler aborts during this callback (or - * the process exits) another status update will be delivered (note, - * however, that this is currently not true if the slave sending the - * status update is lost/fails during that time). If explicit - * acknowledgements are in use, the scheduler must acknowledge this - * status on the driver. - */ - virtual void statusUpdate(SchedulerDriver* driver, - const TaskStatus& status) = 0; - - /** - * Invoked when an executor sends a message. These messages are best - * effort; do not expect a framework message to be retransmitted in - * any reliable fashion. - */ - virtual void frameworkMessage(SchedulerDriver* driver, - const ExecutorID& executorId, - const SlaveID& slaveId, - const std::string& data) = 0; - - /** - * Invoked when a slave has been determined unreachable (e.g., - * machine failure, network partition). Most frameworks will need to - * reschedule any tasks launched on this slave on a new slave. - */ - virtual void slaveLost(SchedulerDriver* driver, - const SlaveID& slaveId) = 0; - - /** - * Invoked when an executor has exited/terminated. Note that any - * tasks running will have TASK_LOST status updates automagically - * generated. - */ - virtual void executorLost(SchedulerDriver* driver, - const ExecutorID& executorId, - const SlaveID& slaveId, - int status) = 0; - - /** - * Invoked when there is an unrecoverable error in the scheduler or - * scheduler driver. The driver will be aborted BEFORE invoking this - * callback. - */ - virtual void error(SchedulerDriver* driver, const std::string& message) = 0; -``` +/* + * Invoked when the scheduler becomes "disconnected" from the master + * (e.g., the master fails and another is taking over). + */ +virtual void disconnected(SchedulerDriver* driver) = 0; + +/* + * Invoked when resources have been offered to this framework. A + * single offer will only contain resources from a single slave. + * Resources associated with an offer will not be re-offered to + * _this_ framework until either (a) this framework has rejected + * those resources (see SchedulerDriver::launchTasks) or (b) those + * resources have been rescinded (see Scheduler::offerRescinded). + * Note that resources may be concurrently offered to more than one + * framework at a time (depending on the allocator being used). In + * that case, the first framework to launch tasks using those + * resources will be able to use them while the other frameworks + * will have those resources rescinded (or if a framework has + * already launched tasks with those resources then those tasks will + * fail with a TASK_LOST status and a message saying as much). + */ +virtual void resourceOffers(SchedulerDriver* driver, + const std::vector<Offer>& offers) = 0; + +/* + * Invoked when an offer is no longer valid (e.g., the slave was + * lost or another framework used resources in the offer). If for + * whatever reason an offer is never rescinded (e.g., dropped + * message, failing over framework, etc.), a framwork that attempts + * to launch tasks using an invalid offer will receive TASK_LOST + * status updats for those tasks (see Scheduler::resourceOffers). + */ +virtual void offerRescinded(SchedulerDriver* driver, + const OfferID& offerId) = 0; + +/* + * Invoked when the status of a task has changed (e.g., a slave is + * lost and so the task is lost, a task finishes and an executor + * sends a status update saying so, etc). If implicit + * acknowledgements are being used, then returning from this + * callback _acknowledges_ receipt of this status update! If for + * whatever reason the scheduler aborts during this callback (or + * the process exits) another status update will be delivered (note, + * however, that this is currently not true if the slave sending the + * status update is lost/fails during that time). If explicit + * acknowledgements are in use, the scheduler must acknowledge this + * status on the driver. + */ +virtual void statusUpdate(SchedulerDriver* driver, + const TaskStatus& status) = 0; + +/* + * Invoked when an executor sends a message. These messages are best + * effort; do not expect a framework message to be retransmitted in + * any reliable fashion. + */ +virtual void frameworkMessage(SchedulerDriver* driver, + const ExecutorID& executorId, + const SlaveID& slaveId, + const std::string& data) = 0; + +/* + * Invoked when a slave has been determined unreachable (e.g., + * machine failure, network partition). Most frameworks will need to + * reschedule any tasks launched on this slave on a new slave. + */ +virtual void slaveLost(SchedulerDriver* driver, + const SlaveID& slaveId) = 0; + +/* + * Invoked when an executor has exited/terminated. Note that any + * tasks running will have TASK_LOST status updates automagically + * generated. + */ +virtual void executorLost(SchedulerDriver* driver, + const ExecutorID& executorId, + const SlaveID& slaveId, + int status) = 0; + +/* + * Invoked when there is an unrecoverable error in the scheduler or + * scheduler driver. The driver will be aborted BEFORE invoking this + * callback. + */ +virtual void error(SchedulerDriver* driver, const std::string& message) = 0; +~~~ ## Create your Framework Executor @@ -136,73 +135,73 @@ Your framework executor must inherit fro Declared in `MESOS_HOME/include/mesos/executor.hpp` -``` - /** - * Invoked once the executor driver has been able to successfully - * connect with Mesos. In particular, a scheduler can pass some - * data to it's executors through the FrameworkInfo.ExecutorInfo's - * data field. - */ - virtual void registered(ExecutorDriver* driver, - const ExecutorInfo& executorInfo, - const FrameworkInfo& frameworkInfo, +~~~{.cpp} +/* + * Invoked once the executor driver has been able to successfully + * connect with Mesos. In particular, a scheduler can pass some + * data to it's executors through the FrameworkInfo.ExecutorInfo's + * data field. + */ +virtual void registered(ExecutorDriver* driver, + const ExecutorInfo& executorInfo, + const FrameworkInfo& frameworkInfo, + const SlaveInfo& slaveInfo) = 0; + +/* + * Invoked when the executor re-registers with a restarted slave. + */ +virtual void reregistered(ExecutorDriver* driver, const SlaveInfo& slaveInfo) = 0; - /** - * Invoked when the executor re-registers with a restarted slave. - */ - virtual void reregistered(ExecutorDriver* driver, - const SlaveInfo& slaveInfo) = 0; - - /** - * Invoked when the executor becomes "disconnected" from the slave - * (e.g., the slave is being restarted due to an upgrade). - */ - virtual void disconnected(ExecutorDriver* driver) = 0; - - /** - * Invoked when a task has been launched on this executor (initiated - * via Scheduler::launchTasks). Note that this task can be realized - * with a thread, a process, or some simple computation, however, no - * other callbacks will be invoked on this executor until this - * callback has returned. - */ - virtual void launchTask(ExecutorDriver* driver, - const TaskInfo& task) = 0; - - /** - * Invoked when a task running within this executor has been killed - * (via SchedulerDriver::killTask). Note that no status update will - * be sent on behalf of the executor, the executor is responsible - * for creating a new TaskStatus (i.e., with TASK_KILLED) and - * invoking ExecutorDriver::sendStatusUpdate. - */ - virtual void killTask(ExecutorDriver* driver, const TaskID& taskId) = 0; - - /** - * Invoked when a framework message has arrived for this - * executor. These messages are best effort; do not expect a - * framework message to be retransmitted in any reliable fashion. - */ - virtual void frameworkMessage(ExecutorDriver* driver, - const std::string& data) = 0; - - /** - * Invoked when the executor should terminate all of it's currently - * running tasks. Note that after a Mesos has determined that an - * executor has terminated any tasks that the executor did not send - * terminal status updates for (e.g., TASK_KILLED, TASK_FINISHED, - * TASK_FAILED, etc) a TASK_LOST status update will be created. - */ - virtual void shutdown(ExecutorDriver* driver) = 0; - - /** - * Invoked when a fatal error has occurred with the executor and/or - * executor driver. The driver will be aborted BEFORE invoking this - * callback. - */ - virtual void error(ExecutorDriver* driver, const std::string& message) = 0; -``` +/* + * Invoked when the executor becomes "disconnected" from the slave + * (e.g., the slave is being restarted due to an upgrade). + */ +virtual void disconnected(ExecutorDriver* driver) = 0; + +/* + * Invoked when a task has been launched on this executor (initiated + * via Scheduler::launchTasks). Note that this task can be realized + * with a thread, a process, or some simple computation, however, no + * other callbacks will be invoked on this executor until this + * callback has returned. + */ +virtual void launchTask(ExecutorDriver* driver, + const TaskInfo& task) = 0; + +/* + * Invoked when a task running within this executor has been killed + * (via SchedulerDriver::killTask). Note that no status update will + * be sent on behalf of the executor, the executor is responsible + * for creating a new TaskStatus (i.e., with TASK_KILLED) and + * invoking ExecutorDriver::sendStatusUpdate. + */ +virtual void killTask(ExecutorDriver* driver, const TaskID& taskId) = 0; + +/* + * Invoked when a framework message has arrived for this + * executor. These messages are best effort; do not expect a + * framework message to be retransmitted in any reliable fashion. + */ +virtual void frameworkMessage(ExecutorDriver* driver, + const std::string& data) = 0; + +/* + * Invoked when the executor should terminate all of it's currently + * running tasks. Note that after a Mesos has determined that an + * executor has terminated any tasks that the executor did not send + * terminal status updates for (e.g., TASK_KILLED, TASK_FINISHED, + * TASK_FAILED, etc) a TASK_LOST status update will be created. + */ +virtual void shutdown(ExecutorDriver* driver) = 0; + +/* + * Invoked when a fatal error has occurred with the executor and/or + * executor driver. The driver will be aborted BEFORE invoking this + * callback. + */ +virtual void error(ExecutorDriver* driver, const std::string& message) = 0; +~~~ ## Install your Framework @@ -216,23 +215,23 @@ When your framework registers an executo The optional `DiscoveryInfo` message for `TaskInfo` and `ExecutorInfo` is declared in `MESOS_HOME/include/mesos/mesos.proto` -``` -message DiscoveryInfo { - enum Visibility { - FRAMEWORK = 0; - CLUSTER = 1; - EXTERNAL = 2; - } - - required Visibility visibility = 1; - optional string name = 2; - optional string environment = 3; - optional string location = 4; - optional string version = 5; - optional Ports ports = 6; - optional Labels labels = 7; -} -``` + + message DiscoveryInfo { + enum Visibility { + FRAMEWORK = 0; + CLUSTER = 1; + EXTERNAL = 2; + } + + required Visibility visibility = 1; + optional string name = 2; + optional string environment = 3; + optional string location = 4; + optional string version = 5; + optional Ports ports = 6; + optional Labels labels = 7; + } + `Visibility` is the key parameter that instructs the service discovery system whether a service should be discoverable. We currently differentiate between three cases: Modified: mesos/site/source/documentation/latest/clang-format.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/clang-format.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/clang-format.md (original) +++ mesos/site/source/documentation/latest/clang-format.md Wed Jul 1 18:55:31 2015 @@ -14,25 +14,25 @@ layout: documentation #### Ubuntu 14.04 -```bash -# Ensure apt-get is up to date. -sudo apt-get update - -# Install clang-format-3.5 -sudo apt-get install clang-format-3.5 -``` + + # Ensure apt-get is up to date. + sudo apt-get update + + # Install clang-format-3.5 + sudo apt-get install clang-format-3.5 + #### OS X Yosemite -```bash -# Install clang-3.5. The binaries are suffixed with '-3.5', e.g. 'clang++-3.5'. -$ brew install llvm35 --with-clang - -# Download and install the clang-format scripts. -$ wget http://llvm.org/releases/3.5.1/cfe-3.5.1.src.tar.xz -$ tar -xzf cfe-3.5.1.src.tar.xz -$ cp cfe-3.5.1.src/tools/clang-format/clang-format* `brew --cellar`/llvm35/3.5.1/share/clang-3.5 -``` + + # Install clang-3.5. The binaries are suffixed with '-3.5', e.g. 'clang++-3.5'. + $ brew install llvm35 --with-clang + + # Download and install the clang-format scripts. + $ wget http://llvm.org/releases/3.5.1/cfe-3.5.1.src.tar.xz + $ tar -xzf cfe-3.5.1.src.tar.xz + $ cp cfe-3.5.1.src/tools/clang-format/clang-format* `brew --cellar`/llvm35/3.5.1/share/clang-3.5 + ### Formatting Configuration @@ -52,17 +52,13 @@ Add the following to your `.vimrc`: Ubuntu: -``` -map <C-K> :pyf /usr/share/vim/addons/syntax/clang-format-3.5.py<cr> -imap <C-K> <c-o>:pyf /usr/share/vim/addons/syntax/clang-format-3.5.py<cr> -``` + map <C-K> :pyf /usr/share/vim/addons/syntax/clang-format-3.5.py<cr> + imap <C-K> <c-o>:pyf /usr/share/vim/addons/syntax/clang-format-3.5.py<cr> OS X: -``` -map <C-K> :pyf /usr/local/share/clang-3.5/clang-format.py<cr> -imap <C-K> <c-o>:pyf /usr/local/share/clang-3.5/clang-format.py<cr> -``` + map <C-K> :pyf /usr/local/share/clang-3.5/clang-format.py<cr> + imap <C-K> <c-o>:pyf /usr/local/share/clang-3.5/clang-format.py<cr> The first line enables clang-format for `NORMAL` and `VISUAL` mode, the second line adds support for `INSERT` mode. Change `C-K` to another binding if you need clang-format on a different key (`C-K` stands for `Ctrl+k`). @@ -78,17 +74,13 @@ Add the following to your `.emacs`: Ubuntu: -``` -(load "/usr/share/emacs/site-lisp/clang-format-3.5/clang-format.el") -(global-set-key [C-M-tab] 'clang-format-region) -``` + (load "/usr/share/emacs/site-lisp/clang-format-3.5/clang-format.el") + (global-set-key [C-M-tab] 'clang-format-region) OS X: -``` -(load "/usr/local/share/clang-3.5/clang-format.el") -(global-set-key [C-M-tab] 'clang-format-region) -``` + (load "/usr/local/share/clang-3.5/clang-format.el") + (global-set-key [C-M-tab] 'clang-format-region) This binds the function `clang-format-region` to `C-M-tab`, which then formats the current line or selected region. Modified: mesos/site/source/documentation/latest/committers.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/committers.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/committers.md (original) +++ mesos/site/source/documentation/latest/committers.md Wed Jul 1 18:55:31 2015 @@ -111,13 +111,6 @@ We'd like to thank the following committ <td>[email protected]</td> </tr> <tr> - <td>+1</td> - <td>Bernd Mathiske</td> - <td>Mesosphere</td> - <td>bernd-mesos</td> - <td>[email protected]</td> - </tr> - <tr> <td>-8</td> <td>Brenden Matthews</td> <td>Mesosphere</td> @@ -160,7 +153,7 @@ We'd like to thank the following committ <td>[email protected]</td> </tr> <tr> - <td>+1</td> + <td>+2</td> <td>Till Toenshoff</td> <td>Mesosphere</td> <td>tillt</td> Modified: mesos/site/source/documentation/latest/configuration.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/configuration.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/configuration.md (original) +++ mesos/site/source/documentation/latest/configuration.md Wed Jul 1 18:55:31 2015 @@ -365,6 +365,17 @@ file:///path/to/file (where file contain </tr> <tr> <td> + --max_slave_ping_timeouts=VALUE + </td> + <td> + The number of times a slave can fail to respond to a + ping from the master. Slaves that incur more than + `max_slave_ping_timeouts` timeouts will be removed. + (default: 5) + </td> + </tr> + <tr> + <td> --modules=VALUE </td> <td> @@ -478,18 +489,6 @@ file:///path/to/file (where file contain </tr> <tr> <td> - --slave_removal_rate_limit=VALUE - </td> - <td> - The maximum rate (e.g., 1/10mins, 2/3hrs, etc) at which slaves will - be removed from the master when they fail health checks. By default - slaves will be removed as soon as they fail the health checks. - <p/> - The value is of the form 'Number of slaves'/'Duration' - </td> - </tr> - <tr> - <td> --registry=VALUE </td> <td> @@ -550,6 +549,29 @@ file:///path/to/file (where file contain </td> </tr> <tr> + <td> + --slave_ping_timeout=VALUE + </td> + <td> + The timeout within which each slave is expected to respond to a + ping from the master. Slaves that do not respond within + `max_slave_ping_timeouts` ping retries will be removed. + (default: 15secs) + </td> + </tr> + <tr> + <td> + --slave_removal_rate_limit=VALUE + </td> + <td> + The maximum rate (e.g., 1/10mins, 2/3hrs, etc) at which slaves will + be removed from the master when they fail health checks. By default + slaves will be removed as soon as they fail the health checks. + <p/> + The value is of the form 'Number of slaves'/'Duration' + </td> + </tr> + <tr> <td> --slave_reregister_timeout=VALUE </td> Modified: mesos/site/source/documentation/latest/docker-containerizer.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/docker-containerizer.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/docker-containerizer.md (original) +++ mesos/site/source/documentation/latest/docker-containerizer.md Wed Jul 1 18:55:31 2015 @@ -58,7 +58,7 @@ set the HOME environment variable pointi ## CommandInfo to run Docker images -A docker image currently supports having a entrypoint and/or a default command. +A docker image currently supports having an entrypoint and/or a default command. To run a docker image with the default command (ie: docker run image), the CommandInfo's value must not be set. If the value is set then it will override the default command. Modified: mesos/site/source/documentation/latest/getting-started.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/getting-started.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/getting-started.md (original) +++ mesos/site/source/documentation/latest/getting-started.md Wed Jul 1 18:55:31 2015 @@ -94,7 +94,7 @@ Following are the instructions for stock ### CentOS 7.1 -- Following are the instructions for stock CentOS 7.1. If you are using a different OS, please install the packages accordingly. +Following are the instructions for stock CentOS 7.1. If you are using a different OS, please install the packages accordingly. # Install a few utility tools $ sudo yum install -y tar wget @@ -133,7 +133,7 @@ Following are the instructions for stock $ ../configure $ make -In order to speed up the build and reduce verbosity of the logs, you can append `-j=<number of cores> V=0` to `make`. +In order to speed up the build and reduce verbosity of the logs, you can append `-j <number of cores> V=0` to `make`. # Run test suite. $ make check Modified: mesos/site/source/documentation/latest/mesos-c++-style-guide.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-c%2B%2B-style-guide.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/mesos-c++-style-guide.md (original) +++ mesos/site/source/documentation/latest/mesos-c++-style-guide.md Wed Jul 1 18:55:31 2015 @@ -12,16 +12,16 @@ The Mesos codebase follows the [Google C * We use [lowerCamelCase](http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms) for variable names (Google uses snake_case, and their class member variables have trailing underscores). * We prepend constructor and function arguments with a leading underscore to avoid ambiguity and / or shadowing: -``` +~~~{.cpp} Try(State _state, T* _t = NULL, const std::string& _message = "") : state(_state), t(_t), message(_message) {} -``` +~~~ * Prefer trailing underscores for use as member fields (but not required). Some trailing underscores are used to distinguish between similar variables in the same scope (think prime symbols), *but this should be avoided as much as possible, including removing existing instances in the code base.* * If you find yourself creating a copy of an argument passed by const reference, consider passing it by value instead (if you don't want to use a leading underscore and copy in the body of the function): -``` +~~~{.cpp} // You can pass-by-value in ProtobufProcess::install() handlers. void Slave::statusUpdate(StatusUpdate update, const UPID& pid) { @@ -30,8 +30,7 @@ void Slave::statusUpdate(StatusUpdate up pid == UPID() ? TaskStatus::SOURCE_SLAVE : TaskStatus::SOURCE_EXECUTOR); ... } -``` - +~~~ ### Constant Names * We use [SCREAMING_SNAKE_CASE](http://en.wikipedia.org/wiki/Letter_case#Special_case_styles) for constant names (Google uses a `k` followed by mixed case, e.g. `kDaysInAWeek`). @@ -64,7 +63,7 @@ void Slave::statusUpdate(StatusUpdate up * Newline when calling or defining a function: indent with 4 spaces. * We do not follow Google's style of wrapping on the open parenthesis, the general goal is to reduce visual "jaggedness" in the code. Prefer (1), (4), (5), sometimes (3), never (2): -``` +~~~{.cpp} // 1: OK. allocator->resourcesRecovered(frameworkId, slaveId, resources, filters); @@ -93,15 +92,15 @@ allocator->resourcesRecovered( // 5: OK. allocator->resourcesRecovered( frameworkId, slaveId, resources, filters); -``` +~~~ ### Continuation * Newline for an assignment statement: indent with 2 spaces. -``` +~~~{.cpp} Try<Duration> failoverTimeout = Duration::create(FrameworkInfo().failover_timeout()); -``` +~~~ ## Empty Lines * 1 blank line at the end of the file. @@ -112,7 +111,7 @@ Try<Duration> failoverTimeout = We disallow capturing **temporaries** by reference. See [MESOS-2629](https://issues.apache.org/jira/browse/MESOS-2629) for the rationale. -``` +~~~{.cpp} Future<Nothing> f() { return Nothing(); } Future<bool> g() { return false; } @@ -150,7 +149,7 @@ const T& t_ = t.member(); // 4: Can also use. const T t = T("Hello").member(); -``` +~~~ We allow capturing non-temporaries by *constant reference* when the intent is to **alias**. @@ -160,7 +159,7 @@ The goal is to make code more concise an * Would benefit from a concise name to provide context for readability. * Will **not** be invalidated during the lifetime of the alias. Otherwise document this explicitly. -``` +~~~{.cpp} hashmap<string, hashset<int>> index; // 1: Ok. @@ -185,49 +184,46 @@ string& s = strings[0]; strings.erase(strings.begin()); s += "world"; // THIS IS A DANGLING REFERENCE! -``` +~~~ ## File Headers * Mesos source files must contain the "ASF" header: -``` -/** - * 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. - */ -``` + /** + * 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. + */ + * Stout and libprocess source files must contain the "Apache License Version 2.0" header: -``` -/** - * 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 - */ -``` + /** + * 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 + */ ## C++11 @@ -237,7 +233,7 @@ We support C++11 and require GCC 4.8+ or * Multiple right angle brackets. * Type inference (`auto` and `decltype`). The main goal is to increase code readability. This is safely the case if the exact same type omitted on the left is already fully stated on the right. Here are several examples: -``` +~~~{.cpp} // 1: OK. const auto& i = values.find(keys.front()); // Compare with @@ -252,7 +248,7 @@ shared_ptr<list<string>> names = shared_ auto authorizer = LocalAuthorizer::create(acls); // Compare with Try<Owned<LocalAuthorizer>> authorizer = LocalAuthorizer::create(); -``` +~~~ * Rvalue references. * Explicitly-defaulted functions. @@ -268,266 +264,306 @@ Try<Owned<LocalAuthorizer>> authorizer = * Lambdas! * Don't put a space between the capture list and the parameter list: - ``` - // 1: OK. - []() { ...; }; - - // 2: Don't use. - [] () { ...; }; - ``` +~~~{.cpp} +// 1: OK. +[]() { ...; }; + +// 2: Don't use. +[] () { ...; }; +~~~ * Prefer default capture by value, explicit capture by value, then capture by reference. To avoid dangling-pointer bugs, *never* use default capture by reference: - ``` - // 1: OK. - [=]() { ... }; // Default capture by value. - [n]() { ... }; // Explicit capture by value. - [&n]() { ... }; // Explicit capture by reference. - [=, &n]() { ... }; // Default capture by value, explicit capture by reference. - - // 2: Don't use. - [&]() { ... }; // Default capture by reference. - ``` +~~~{.cpp} +// 1: OK. +[=]() { ... }; // Default capture by value. +[n]() { ... }; // Explicit capture by value. +[&n]() { ... }; // Explicit capture by reference. +[=, &n]() { ... }; // Default capture by value, explicit capture by reference. + +// 2: Don't use. +[&]() { ... }; // Default capture by reference. +~~~ * Use `mutable` only when absolutely necessary. - ``` - // 1: OK. - []() mutable { ...; }; - ``` +~~~{.cpp} +// 1: OK. +[]() mutable { ...; }; +~~~ * Feel free to ignore the return type by default, adding it as necessary to appease the compiler or be more explicit for the reader. - ``` - // 1: OK. - []() { return true; }; - []() -> bool { return ambiguous(); }; - ``` +~~~{.cpp} +// 1: OK. +[]() { return true; }; +[]() -> bool { return ambiguous(); }; +~~~ * Feel free to use `auto` when naming a lambda expression: - ``` - // 1: OK. - auto lambda = []() { ...; }; - ``` +~~~{.cpp} +// 1: OK. +auto lambda = []() { ...; }; +~~~ * Format lambdas similar to how we format functions and methods. Feel free to let lambdas be one-liners: - ``` - // 1: OK. - auto lambda = []() { - ...; - }; - - // 2: OK. - auto lambda = []() { ...; }; - ``` - - Feel free to inline lambdas within function arguments: - - ``` - instance.method([]() { - ...; - }); - ``` - - Chain function calls on a newline after the closing brace of the lambda and the closing parenthesis of function call: - - ``` - // 1: OK. - instance - .method([]() { - ...; - }) - .then([]() { ...; }) - .then([]() { - ...; - }); - - // 2: OK (when no chaining, compare to 1). - instance.method([]() { - ...; - }); - - // 3: OK (if no 'instance.method'). - function([]() { - ...; - }) - .then([]() { ...; }) - .then([]() { - ...; - }); - - // 3: OK (but prefer 1). - instance.method([]() { - ...; - }) - .then([]() { ...; }) - .then([]() { - ...; - }); - ``` - - Wrap capture lists indepedently of parameters, *use the same formatting as if the capture list were template parameters*: - - - ``` - // 1: OK. - function([&capture1, &capture2, &capture3]( - const T1& p1, const T2& p2, const T3& p3) { - ...; - }); +~~~{.cpp} +// 1: OK. +auto lambda = []() { + ...; +}; + +// 2: OK. +auto lambda = []() { ...; }; +~~~ - function( - [&capture1, &capture2, &capture3]( - const T1& p1, const T2& p2, const T3& p3) { - ...; - }); + * Feel free to inline lambdas within function arguments: - auto lambda = [&capture1, &capture2, &capture3]( - const T1& p1, const T2& p2, const T3& p3) { - ...; - }; +~~~{.cpp} +instance.method([]() { + ...; +}); +~~~ + * Chain function calls on a newline after the closing brace of the lambda and the closing parenthesis of function call: - auto lambda = - [&capture1, &capture2, &capture3]( - const T1& p1, const T2& p2, const T3& p3) { - ...; - }; - - // 2: OK (when capture list is longer than 80 characters). - function([ - &capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, const T2& p2) { - ...; - }); - - auto lambda = [ - &capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, const T2& p2) { - ...; - }; - - // 3: OK (but prefer 2). - function([ - &capture1, - &capture2, - &capture3, - &capture4](const T1& p1, const T2& t2) { - ...; - }); - - auto lambda = [ - &capture1, - &capture2, - &capture3, - &capture4](const T1& p1, const T2& p2) { - ...; - }; - - // 3: Don't use. - function([&capture1, - &capture2, - &capture3, - &capture4](const T1& p1, const T2& p2) { - ...; - }); - - auto lambda = [&capture1, - &capture2, - &capture3, - &capture4](const T1& p1, const T2& p2) { - ...; - }; - - // 4: Don't use. - function([&capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, const T2& p2, const T3& p3) { - ...; - }); +~~~{.cpp} +// 1: OK. +instance + .method([]() { + ...; + }) + .then([]() { ...; }) + .then([]() { + ...; + }); + +// 2: OK (when no chaining, compare to 1). +instance.method([]() { + ...; +}); + +// 3: OK (if no 'instance.method'). +function([]() { + ...; +}) +.then([]() { ...; }) +.then([]() { + ...; +}); + +// 3: OK (but prefer 1). +instance.method([]() { + ...; +}) +.then([]() { ...; }) +.then([]() { + ...; +}); +~~~ + + * Wrap capture lists indepedently of parameters, *use the same formatting as if the capture list were template parameters*: + +~~~{.cpp} +// 1: OK. +function([&capture1, &capture2, &capture3]( + const T1& p1, const T2& p2, const T3& p3) { + ...; +}); - auto lambda = [&capture1, - &capture2, - &capture3, - &capture4]( +function( + [&capture1, &capture2, &capture3]( const T1& p1, const T2& p2, const T3& p3) { - ...; - }; + ...; +}); - // 5: Don't use. - function([&capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, - const T2& p2, - const T3& p3) { - ...; - }); - - auto lambda = [&capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, - const T2& p2, - const T3& p3) { - ...; - }; +auto lambda = [&capture1, &capture2, &capture3]( + const T1& p1, const T2& p2, const T3& p3) { + ...; +}; + +auto lambda = + [&capture1, &capture2, &capture3]( + const T1& p1, const T2& p2, const T3& p3) { + ...; +}; + +// 2: OK (when capture list is longer than 80 characters). +function([ + &capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, const T2& p2) { + ...; +}); + +auto lambda = [ + &capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, const T2& p2) { + ...; +}; + +// 3: OK (but prefer 2). +function([ + &capture1, + &capture2, + &capture3, + &capture4](const T1& p1, const T2& t2) { + ...; +}); + +auto lambda = [ + &capture1, + &capture2, + &capture3, + &capture4](const T1& p1, const T2& p2) { + ...; +}; + +// 3: Don't use. +function([&capture1, + &capture2, + &capture3, + &capture4](const T1& p1, const T2& p2) { + ...; +}); + +auto lambda = [&capture1, + &capture2, + &capture3, + &capture4](const T1& p1, const T2& p2) { + ...; + }; + +// 4: Don't use. +function([&capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, const T2& p2, const T3& p3) { + ...; +}); + +auto lambda = [&capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, const T2& p2, const T3& p3) { + ...; +}; - // 6: OK (parameter list longer than 80 characters). - function([&capture1, &capture2, &capture3]( +// 5: Don't use. +function([&capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, + const T2& p2, + const T3& p3) { + ...; + }); + +auto lambda = [&capture1, + &capture2, + &capture3, + &capture4]( + const T1& p1, + const T2& p2, + const T3& p3) { + ...; +}; + +// 6: OK (parameter list longer than 80 characters). +function([&capture1, &capture2, &capture3]( + const T1& p1, + const T2& p2, + const T3& p3, + const T4& p4) { + ...; +}); + +auto lambda = [&capture1, &capture2, &capture3]( + const T1& p1, + const T2& p2, + const T3& p3, + const T4& p4) { + ...; +}; + +// 7: OK (capture and parameter lists longer than 80 characters). +function([ + &capture1, + &capture2, + &capture3, + &capture4]( const T1& p1, const T2& p2, const T3& p3, const T4& p4) { - ...; - }); + ...; +}); - auto lambda = [&capture1, &capture2, &capture3]( +auto lambda = [ + &capture1, + &capture2, + &capture3, + &capture4]( const T1& p1, const T2& p2, const T3& p3, const T4& p4) { - ...; - }; - - // 7: OK (capture and parameter lists longer than 80 characters). - function([ - &capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, - const T2& p2, - const T3& p3, - const T4& p4) { - ...; - }); - - auto lambda = [ - &capture1, - &capture2, - &capture3, - &capture4]( - const T1& p1, - const T2& p2, - const T3& p3, - const T4& p4) { - ...; - }; - ``` + ...; +}; +~~~ * Unrestricted Union. Like the pre-existing `union`, we can overlap storage allocation for objects that never exist simultaneously. However, with C++11 we are no longer *restricted to having only non-POD types in unions*. 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., `Option`, `Try`, `Result`, etc. In effect, we treat the union like a dynamic allocation, calling *placement new*, `new (&t) T(...)` anyplace we would have just called `new T(...)` and the destructor `t.~T()` anyplace we would have called `delete t`. + +* Constant expressions. + + 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 `constexpr` to `const` can propagate through the dependency tree requiring that dependent `constexpr` uses also be converted to `const`, hence we avoid using `constexpr` in complex functions. + + `constexpr` behaves as a combination of `inline` and `const` and hence must be defined before use in another `constexpr`. + + Prefer `constexpr to `const` for all constant POD declarations, `constexpr` `char` arrays are preferred to `const` `string` literals. + ``` + // OK + constexpr char LITERAL[] = "value"; + + // Not OK - not available at compile time for optimization and + // definition required in a separate compilation module. + const char LITERAL[]; + + // Not OK - uncertain initialization order, cannot be used in other + // constexpr statements. + const string LITERAL("value"); + + ``` + `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. + + ``` + constexpr size_t MIN = 200; + constexpr size_t MAX = 1000; + constexpr size_t SPAN() { return MAX-MIN; } + int array[SPAN()]; + ``` + 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. + ``` + class C + { + public: + constexpr C(int _i) : i(_i) {}; + constexpr C(const C& c) : i(c.i) {} + private: + const int i; + }; + + ``` + 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. Added: mesos/site/source/documentation/latest/mesos-documentation-guide.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-documentation-guide.md?rev=1688707&view=auto ============================================================================== --- mesos/site/source/documentation/latest/mesos-documentation-guide.md (added) +++ mesos/site/source/documentation/latest/mesos-documentation-guide.md Wed Jul 1 18:55:31 2015 @@ -0,0 +1,35 @@ +# Mesos Documentation Guide + +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. + +We have three different kinds of documentation: + + +1. [MarkDown User Guides](/documentation/latest/mesos-markdown-style-guide/) + + User guides and non-code technical documentation are stored in markdown files in the `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/). + + +2. [Doxygen API Documentation and Developer Guides as part of source code](/documentation/latest/mesos-doxygen-style-guide/) + + 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. + + 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. + + +3. Regular source code documentation + + All other source code comments must follow the [Google Style Guide](https://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Comments). + + +## Conventions + +We follow the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) +on how to use words such as "must", "should", "can", +and other requirement-related notions. Modified: mesos/site/source/documentation/latest/mesos-doxygen-style-guide.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-doxygen-style-guide.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/mesos-doxygen-style-guide.md (original) +++ mesos/site/source/documentation/latest/mesos-doxygen-style-guide.md Wed Jul 1 18:55:31 2015 @@ -6,54 +6,8 @@ using [Doxygen](http://www.doxygen.org). 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. -## Preliminaries -We follow the [IETF RFC2119](https://www.ietf.org/rfc/rfc2119.txt) -on how to use words such as "must", "should", "can", -and other requirement-related notions. - - -## Building Doxygen Documentation -As of right now, the Doxygen documentation should be built from the *build* subdirectory using *doxygen ../Doxyfile* . The documentation will then be generated into the *./doxygen* subdirectory. -Todo: We should create a regular make target. - - -## Doxygen Tags -*When following these links be aware that the doxygen documentation is using another syntax in that @param is explained as \param.* - -* [@param](http://doxygen.org/manual/commands.html#cmdparam) Describes function parameters. -* [@return](http://doxygen.org/manual/commands.html#cmdreturn) Describes return values. -* [@see](http://doxygen.org/manual/commands.html#cmdsa) Describes a cross-reference to classes, functions, methods, variables, files or URL. -* [@file](http://doxygen.org/manual/commands.html#cmdfile) Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files. -* [@link](http://doxygen.org/manual/commands.html#cmdlink) and [@endlink](http://doxygen.org/manual/commands.html#cmdendlink) Describes a link to a file, class, or member. -* [@example](http://doxygen.org/manual/commands.html#cmdexample) Describes source code examples. -* [@todo](http://doxygen.org/manual/commands.html#cmdtodo) Describes a TODO item. -* [@image](http://doxygen.org/manual/commands.html#cmdimage) Describes an image. - -## Wrapping -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. -~~~ - - -## Outside Source Code - -### Library and Component Overview Pages and User Guides - -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. - -This page must be located in the top directory of the library/component and named "REAMDE.md". - -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" - -## In Source Code +## Source Code Documentation Syntax Doxygen documentation needs only to be applied to source code parts that constitute an interface for which we want to generate Mesos API documentation @@ -63,6 +17,13 @@ enhanced by source code comments as appr We follow the [Javadoc syntax](http://en.wikipedia.org/wiki/Javadoc) to mark comment blocks. These have the general form: + +<!-- 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. --> + + /** * Brief summary. * @@ -85,18 +46,143 @@ Example: */ std::string compress(const std::string& uncompressed); + +### Doxygen Tags + +This is the allowed set of doxygen tags that can be used. + + * [\@param](http://doxygen.org/manual/commands.html#cmdparam) Describes function parameters. + * [\@return](http://doxygen.org/manual/commands.html#cmdreturn) Describes return values. + * [\@see](http://doxygen.org/manual/commands.html#cmdsa) Describes a cross-reference to classes, functions, methods, variables, files or URL. + * [\@file](http://doxygen.org/manual/commands.html#cmdfile) Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files. + * [\@link](http://doxygen.org/manual/commands.html#cmdlink) and [\@endlink](http://doxygen.org/manual/commands.html#cmdendlink) Describes a link to a file, class, or member. + * [\@example](http://doxygen.org/manual/commands.html#cmdexample) Describes source code examples. + * [\@todo](http://doxygen.org/manual/commands.html#cmdtodo) Describes a TODO item. + * [\@image](http://doxygen.org/manual/commands.html#cmdimage) Describes an image. + + * When following these links be aware that the doxygen documentation is using another syntax in that \@param is explained as \\param. + + +### Wrapping + +We wrap long descriptions using four 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. + + ### Constants and Variables -### Functions +Example: -### Classes + /** + * 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; -#### Methods #### Fields -### Templates +Example: + + /** + * 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; + + +### Functions and Methods + +Example: + + /** + * 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()); + + +### Classes and Structs + +Example: + + /** + * 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: + -### Macros +## Library and Component Overview Pages and Developer Guides -### Global declarations outside classes +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. + +This page must be located in the top directory of the library/component and named "REAMDE.md". + +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" + +### Example Code + +C++ code examples should be enclosed by '~~~{.cpp}'. + +Example: + +~~~{.cpp} +int main(int argc, char** argv) +{ + ... +} +~~~ + +**NOTE**: Because of shortcomings of Doxygen's markdown parser we currently use indentation for wrapping all non C++ code blocks. + + +## Building Doxygen Documentation + +As of right now, the Doxygen documentation should be built from the *build* subdirectory using *doxygen ../Doxyfile* . The documentation will then be generated into the *./doxygen* subdirectory. Added: mesos/site/source/documentation/latest/mesos-markdown-style-guide.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-markdown-style-guide.md?rev=1688707&view=auto ============================================================================== --- mesos/site/source/documentation/latest/mesos-markdown-style-guide.md (added) +++ mesos/site/source/documentation/latest/mesos-markdown-style-guide.md Wed Jul 1 18:55:31 2015 @@ -0,0 +1,118 @@ +# Mesos Markdown Style Guide + +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 `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/). + +**NOTE:** As of right now this is work in progress and the existing documentation might not yet comply to this style. + + +## What to document? + +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. + + +## Keep documentation and style-guides in sync with code. + +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 `configuration.md`! + + +## Code Examples + +Code examples should be specified as follows: + + ~~~{.cpp} + int main(int argc, char** argv) + { + .... + } + ~~~ + +**NOTE:** Because of shortcomings of Doxygen's markdown parser we currently use indentation for wrapping all non C++ code blocks. + +## Notes/Emphasis + +Notes are used to highlight important parts of the text and should be specified as follows. + +~~~{.txt} +**NOTE:** Short note. +Continued longer note. +~~~ + +We use single backticks to highlight individual words in a sentence such as certain identifiers: + +~~~{.txt} +Use the default `HierarchicalDRF` allocator.... +~~~ + + +## Commands + +We use single backticks to highlight sample commands as follows: + +~~~{.txt} +`mesos-master --help` +~~~ + + +## Files/Path + +Files and path references should be specified as follows: + +~~~{.text} +Remember you can also use the `file:///path/to/file` or `/path/to/file` +~~~ + + +## Tables + +In order to avoid problems with markdown formatting we should specify tables in html directly: + +~~~{.html} +<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> +~~~ + + +## 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. + +~~~{.txt} +... end of previous section. + + +## New Section + +Beginning of new section .... +~~~ Added: mesos/site/source/documentation/latest/mesos-ssl.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-ssl.md?rev=1688707&view=auto ============================================================================== --- mesos/site/source/documentation/latest/mesos-ssl.md (added) +++ mesos/site/source/documentation/latest/mesos-ssl.md Wed Jul 1 18:55:31 2015 @@ -0,0 +1,89 @@ +--- +layout: documentation +--- + +#Configuration +There is currently only one implementation of the [libprocess socket interface](https://github.com/apache/mesos/blob/master/3rdparty/libprocess/include/process/socket.hpp) that supports SSL. This implementation uses [libevent](https://github.com/libevent/libevent). Specifically it relies on the `libevent-openssl` library that wraps `openssl`. + +After building `Mesos 0.23.0` from source, assuming you have installed the required [Dependencies](#Dependencies), you can modify your configure line to enable SSL as follows: + +~~~ +../configure --enable-libevent --enable-ssl +~~~ + +#Running +Once you have successfully built and installed your new binaries, here are the environment variables that are applicable to the `Master`, `Slave`, `Framework Scheduler/Executor`, or any `libprocess process`: + +#####SSL_ENABLED=(false|0,true|1) [default=false|0] +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. + +#####SSL_SUPPORT_DOWNGRADE=(false|0,true|1) [default=false|0] +Control whether or not non-SSL connections can be established. If this is enabled __on the accepting side__, 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 [Upgrading Your Cluster](#Upgrading) for more details. + +#####SSL_CERT_FILE=(path to certificate) +The location of the certificate this binary will present. + +#####SSL_KEY_FILE=(path to key) +The location of the private key used by OpenSSL. + +#####SSL_VERIFY_CERT=(false|0,true|1) [default=false|0] +Control whether certificates are verified when presented. If this is false, even when a certificate is presented, it will not be verified. When `SSL_REQUIRE_CERT` is true, `SSL_VERIFY_CERT` is overridden and all certificates will be verified _and_ required. + +#####SSL_REQUIRE_CERT=(false|0,true|1) [default=false|0] +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. + +#####SSL_VERIFY_DEPTH=(4) [default=4] +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. + +#####SSL_CA_DIR=(path to CA directory) +The directory used to find the certificate authority / authorities. You can specify `SSL_CA_DIR` or `SSL_CA_FILE` depending on how you want to restrict your certificate authorization. + +#####SSL_CA_FILE=(path to CA file) +The file used to find the certificate authority. You can specify `SSL_CA_DIR` or `SSL_CA_FILE` depending on how you want to restrict your certificate authorization. + +#####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] +A list of `:`-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. + +#####SSL_ENABLE_SSL_V2=(false|0,true|1) [default=false|0] +#####SSL_ENABLE_SSL_V3=(false|0,true|1) [default=false|0] +#####SSL_ENABLE_TLS_V1_0=(false|0,true|1) [default=false|0] +#####SSL_ENABLE_TLS_V1_1=(false|0,true|1) [default=false|0] +#####SSL_ENABLE_TLS_V1_2=(false|0,true|1) [default=true|1] +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. +#<a name="Dependencies"></a>Dependencies + +### libevent +We require the OpenSSL support from libevent. The suggested version of libevent is [`2.0.22-stable`](https://github.com/libevent/libevent/releases/tag/release-2.0.22-stable). As new releases come out we will try to maintain compatibility. +~~~ +// For example, on OSX: +brew install libevent +~~~ + +### OpenSSL +We require [OpenSSL](https://github.com/openssl/openssl). 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 `event2` and `openssl` headers are available for building mesos. +~~~ +// For example, on OSX: +brew install openssl +~~~ + +#<a name="Upgrading"></a>Upgrading Your Cluster +_There is no SSL specific requirement for upgrading different components in a specific order._ + +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. _Please note:_ 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 [WebUI](#WebUI) 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> + +// 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. + +_Please note:_ 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 `SSL_SUPPORT_DOWNGRADE=true` for some time as you upgrade your internal tooling. The advantage of `SSL_SUPPORT_DOWNGRADE=true` is that all components that speak SSL will do so, while other components may still communicate over insecure channels. + +#<a name="WebUI"></a>WebUI +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. + +###Certificates +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. Modified: mesos/site/source/documentation/latest/mesos-testing-patterns.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-testing-patterns.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/mesos-testing-patterns.md (original) +++ mesos/site/source/documentation/latest/mesos-testing-patterns.md Wed Jul 1 18:55:31 2015 @@ -13,51 +13,51 @@ Scheduling a sequence of events in an as Every message enqueued in a libprocess process' (or actor's, to avoid ambiguity with OS processes) mailbox is processed by `ProcessManager` (right now there is a single instance of `ProcessManager` per OS process, but this may change in the future). `ProcessManager` fetches actors from the runnable actors list and services all events from the actor's mailbox. Using `Clock::settle()` call we can block the calling thread until `ProcessManager` empties mailboxes of all actors. Here is the example of this pattern: ~~~{.cpp} - // As Master::killTask isn't doing anything, we shouldn't get a status update. - EXPECT_CALL(sched, statusUpdate(&driver, _)) - .Times(0); +// 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(); ~~~ ## Intercepting a message sent to a different OS process 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.: ~~~{.cpp} - Future<SlaveReregisteredMessage> slaveReregisteredMessage = - FUTURE_PROTOBUF(SlaveReregisteredMessage(), _, _); - ... - AWAIT_READY(slaveReregisteredMessage); +Future<SlaveReregisteredMessage> slaveReregisteredMessage = + FUTURE_PROTOBUF(SlaveReregisteredMessage(), _, _); +... +AWAIT_READY(slaveReregisteredMessage); ~~~ However, this won't work if we want to intercept a message sent to an actor (technically a `UPID`) that lives in another OS process. For example, `CommandExecutor` 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 `mesos/src/tests/cluster.hpp`). The wait in this code will fail: ~~~{.cpp} - Future<ExecutorRegisteredMessage> executorRegisteredMessage = - FUTURE_PROTOBUF(ExecutorRegisteredMessage(), _, _); - ... - AWAIT_READY(executorRegisteredMessage); +Future<ExecutorRegisteredMessage> executorRegisteredMessage = + FUTURE_PROTOBUF(ExecutorRegisteredMessage(), _, _); +... +AWAIT_READY(executorRegisteredMessage); ~~~ ### Why messages sent outside the OS process are not intercepted? @@ -71,11 +71,11 @@ Consider setting expectations on corresp For the aforementioned example, instead of intercepting `ExecutorRegisteredMessage`, we can intercept `RegisterExecutorMessage` and wait until its processed, which includes sending `ExecutorRegisteredMessage` (see `Slave::registerExecutor()`): ~~~{.cpp} - Future<RegisterExecutorMessage> registerExecutorMessage = - FUTURE_PROTOBUF(RegisterExecutorMessage(), _, _); - ... - AWAIT_READY(registerExecutorMessage); - Clock::pause(); - Clock::settle(); - Clock::resume(); +Future<RegisterExecutorMessage> registerExecutorMessage = + FUTURE_PROTOBUF(RegisterExecutorMessage(), _, _); +... +AWAIT_READY(registerExecutorMessage); +Clock::pause(); +Clock::settle(); +Clock::resume(); ~~~ Modified: mesos/site/source/documentation/latest/modules.md URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/modules.md?rev=1688707&r1=1688706&r2=1688707&view=diff ============================================================================== --- mesos/site/source/documentation/latest/modules.md (original) +++ mesos/site/source/documentation/latest/modules.md Wed Jul 1 18:55:31 2015 @@ -47,57 +47,53 @@ Use `--modules="{...}"` to specify the l 1. Load a library `libfoo.so` with two modules `org_apache_mesos_bar` and `org_apache_mesos_baz`. - ``` - { - "libraries": [ - { - "file": "/path/to/libfoo.so", - "modules": [ - { - "name": "org_apache_mesos_bar", - }, - { - "name": "org_apache_mesos_baz" - } - ] - } - ] - } - ``` + { + "libraries": [ + { + "file": "/path/to/libfoo.so", + "modules": [ + { + "name": "org_apache_mesos_bar", + }, + { + "name": "org_apache_mesos_baz" + } + ] + } + ] + } + 2. Load the module `org_apache_mesos_bar` from the library `foo` and pass the command-line argument `X` with value `Y` (module `org_apache_mesos_baz` is loaded without any command-line parameters): - ``` - { - "libraries": [ - { - "name": "foo", - "modules": [ - { - "name": "org_apache_mesos_bar" - "parameters": [ - { - "key": "X", - "value": "Y", - } - ] - }, - { - "name": "org_apache_mesos_bar" - } - ] - } - ] - } - ``` + { + "libraries": [ + { + "name": "foo", + "modules": [ + { + "name": "org_apache_mesos_bar" + "parameters": [ + { + "key": "X", + "value": "Y", + } + ] + }, + { + "name": "org_apache_mesos_bar" + } + ] + } + ] + } 3. Specifying modules inline: - ``` - --modules='{"libraries":[{"file":"/path/to/libfoo.so", "modules":[{"name":"org_apache_mesos_bar"}]}]}' - ``` + --modules='{"libraries":[{"file":"/path/to/libfoo.so", "modules":[{"name":"org_apache_mesos_bar"}]}]}' + ### Library names @@ -131,9 +127,8 @@ To load a custom allocator into Mesos ma For example, the following command will run the Mesos master with `ExternalAllocatorModule` (see [this section](#Example-JSON-strings) for JSON format): -``` -./bin/mesos-master.sh --work_dir=m/work --modules="file://<modules-including-allocator>.json" --allocator=ExternalAllocatorModule -``` + ./bin/mesos-master.sh --work_dir=m/work --modules="file://<modules-including-allocator>.json" --allocator=ExternalAllocatorModule + ### Anonymous @@ -208,9 +203,8 @@ To load a hook into Mesos, you need to For example, the following command will run the Mesos slave with the `TestTaskHook` hook: -``` -./bin/mesos-slave.sh --master=<IP>:<PORT> --modules="file://<path-to-modules-config>.json" --hooks=TestTaskHook -``` + ./bin/mesos-slave.sh --master=<IP>:<PORT> --modules="file://<path-to-modules-config>.json" --hooks=TestTaskHook + ### Isolator @@ -225,62 +219,61 @@ for GPGPU hardware, networking, etc. The following snippet describes the implementation of a module named "org_apache_mesos_bar" of "TestModule" kind: -``` - #include <iostream> - #include "test_module.hpp" - - class TestModuleImpl : public TestModule +~~~{.cpp} +#include <iostream> +#include "test_module.hpp" + +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; } +}; - // 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", - "[email protected]", - "This is a test module.", - compatible, - create); -``` +static TestModule* create() +{ + return new TestModule(); +} + +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", + "[email protected]", + "This is a test module.", + compatible, + create); +~~~ ### Building a module The following assumes that Mesos is installed in the standard location, i.e. the Mesos dynamic library and header files are available. -``` - g++ -lmesos -fpic -o test_module.o test_module.cpp - $ gcc -shared -o libtest_module.so test_module.o -``` + + g++ -lmesos -fpic -o test_module.o test_module.cpp + $ gcc -shared -o libtest_module.so test_module.o ### Testing a modules @@ -288,9 +281,9 @@ Apart from testing the module by hand wi can run the entire mesos test suite with the given module. For example, the following command will run the mesos test suite with the `org_apache_mesos_TestCpuIsolator` module selected for isolation: -``` -./bin/mesos-tests.sh --modules="/home/kapil/mesos/isolator-module/modules.json" --isolation="org_apache_mesos_TestCpuIsolator" -``` + + ./bin/mesos-tests.sh --modules="/home/kapil/mesos/isolator-module/modules.json" --isolation="org_apache_mesos_TestCpuIsolator" + ### Module naming convention Each module name should be unique. Having duplicate module names in the Json @@ -371,7 +364,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> @@ -394,54 +386,51 @@ Initial version of the modules API. ## Appendix: ### JSON Schema: -``` - { - "type":"object", - "required":false, - "properties":{ - "libraries": { - "type":"array", - "required":false, - "items": - { - "type":"object", + { + "type":"object", + "required":false, + "properties":{ + "libraries":{ + "type":"array", "required":false, - "properties":{ - "file": { - "type":"string", - "required":false - }, - "name": { - "type":"string", - "required":false - }, - "modules": { - "type":"array", - "required":false, - "items": - { - "type":"object", + "items":{ + "type":"object", + "required":false, + "properties":{ + "file":{ + "type":"string", + "required":false + }, + "name":{ + "type":"string", + "required":false + }, + "modules":{ + "type":"array", "required":false, - "properties":{ - "name": { - "type":"string", - "required":true - }, - "parameters": { - "type":"array", - "required":false, - "items": - { - "type":"object", + "items":{ + "type":"object", + "required":false, + "properties":{ + "name":{ + "type":"string", + "required":true + }, + "parameters":{ + "type":"array", "required":false, - "properties":{ - "key": { - "type":"string", - "required":true - }, - "value": { - "type":"string", - "required":true + "items":{ + "type":"object", + "required":false, + "properties":{ + "key":{ + "type":"string", + "required":true + }, + "value":{ + "type":"string", + "required":true + } } } } @@ -453,5 +442,3 @@ Initial version of the modules API. } } } - } -```
