wrote documentation for WAL

Documentation/Books/Users/FirstSteps/README.mdpp

@@ -21,7 +21,7 @@ Key features include:
   durability or more performance
 * *No-nonsense storage*: ArangoDB uses all of the power of modern storage
   hardware, like SSD and large caches
-* *Powerful query language* (AQL) to retrieve data 
+* *Powerful query language* (AQL) to retrieve and modify data 
 * *Transactions*: Run queries on multiple documents or collections with 
   optional transactional consistency and isolation
 * *Replication*: Set up the database in a master-slave configuration

Documentation/Books/Users/HttpMiscellaneousFunctions/README.mdpp

@@ -7,6 +7,21 @@ This is an overview of ArangoDB's HTTP interface for miscellaneous functions.
 @startDocuBlock JSF_get_api_return
 
 
+<!-- ljs/actions/api-system.js -->
+
+@startDocuBlock JSF_put_admin_wal_flush
+
+
+<!-- ljs/actions/api-system.js -->
+
+@startDocuBlock JSF_get_admin_wal_properties
+
+
+<!-- ljs/actions/api-system.js -->
+
+@startDocuBlock JSF_put_admin_wal_properties
+
+
 <!-- js/actions/api-system.js -->
 
 @startDocuBlock JSF_get_admin_time
@@ -19,4 +34,4 @@ This is an overview of ArangoDB's HTTP interface for miscellaneous functions.
 
 <!-- lib/Admin/RestShutdownHandler.cpp -->
 
-@startDocuBlock JSF_get_api_initiate
+@startDocuBlock JSF_get_api_initiate

Documentation/Books/Users/ModuleWal/README.mdpp

@@ -0,0 +1,16 @@
+!CHAPTER Write-ahead log 
+
+This module provides functionality for administering the write-ahead logs.
+
+!SUBSECTION Configuration
+<!-- arangod/V8Server/v8-vocbase.h -->
+@startDocuBlock walPropertiesGet
+
+<!-- arangod/V8Server/v8-vocbase.h -->
+@startDocuBlock walPropertiesSet
+
+!SUBSECTION Flushing
+
+<!-- arangod/V8Server/v8-vocbase.h -->
+@startDocuBlock walFlush
+

Documentation/Books/Users/NamingConventions/AttributeNames.mdpp

@@ -13,7 +13,7 @@ following attribute naming constraints are not violated:
   end users should not use attribute names starting with an underscore for their
   own attributes.
 
-* Attribute names should not start with the at-mark (*\@*). The at-mark
+* Attribute names should not start with the at-mark (*@*). The at-mark
   at the start of attribute names is reserved in ArangoDB for future use cases.
 * Theoretically, attribute names can include punctuation and special characters
   as desired, provided the name is a valid UTF-8 string.  For maximum

Documentation/Books/Users/SUMMARY.md

@@ -198,6 +198,7 @@
     * [Edge Methods](ModuleGraph/EdgeMethods.md)
   * ["actions"](ModuleActions/README.md)
   * ["planner"](ModulePlanner/README.md)
+  * [Write-ahead log](ModuleWal/README.md)
   * [Task Management](ModuleTasks/README.md)
   * [Using jsUnity](UsingJsUnity/README.md)
 <!-- 25 -->

arangod/V8Server/v8-vocbase.cpp

@@ -3861,7 +3861,62 @@ static v8::Handle<v8::Value> JS_Transaction (v8::Arguments const& argv) {
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief adjusts the WAL configuration at runtime
+/// @brief retrieves the configuration of the write-ahead log
+/// @startDocuBlock walPropertiesGet
+/// `internal.wal.properties()`
+///
+/// Retrieves the configuration of the write-ahead log. The result is a JSON
+/// array with the following attributes:
+/// - *allowOversizeEntries*: whether or not operations that are bigger than a
+///   single logfile can be executed and stored
+/// - *logfileSize*: the size of each write-ahead logfile
+/// - *historicLogfiles*: the maximum number of historic logfiles to keep
+/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB
+///   allocates in the background
+/// - *syncInterval*: the interval for automatic synchronization of not-yet
+///   synchronized write-ahead log data (in milliseconds)
+/// - *throttleWait*: the maximum wait time that operations will wait before
+///   they get aborted if case of write-throttling (in milliseconds)
+/// - *throttleWhenPending*: the number of unprocessed garbage-collection 
+///   operations that, when reached, will activate write-throttling. A value of
+///   *0* means that write-throttling will not be triggered.
+///
+/// @EXAMPLES
+///
+/// @EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesGet}
+///   require("internal").wal.properties();
+/// @END_EXAMPLE_ARANGOSH_OUTPUT
+/// @endDocuBlock
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief configures the write-ahead log
+/// @startDocuBlock walPropertiesSet
+/// `internal.wal.properties(properties)`
+///
+/// Configures the behavior of the write-ahead log. *properties* must be a JSON
+/// JSON object with the following attributes:
+/// - *allowOversizeEntries*: whether or not operations that are bigger than a 
+///   single logfile can be executed and stored
+/// - *logfileSize*: the size of each write-ahead logfile
+/// - *historicLogfiles*: the maximum number of historic logfiles to keep
+/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB
+///   allocates in the background
+/// - *throttleWait*: the maximum wait time that operations will wait before
+///   they get aborted if case of write-throttling (in milliseconds)
+/// - *throttleWhenPending*: the number of unprocessed garbage-collection 
+///   operations that, when reached, will activate write-throttling. A value of
+///   *0* means that write-throttling will not be triggered.
+///
+/// Specifying any of the above attributes is optional. Not specified attributes
+/// will be ignored and the configuration for them will not be modified.
+///
+/// @EXAMPLES
+///
+/// @EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesSet}
+///   require("internal").wal.properties({ allowOverSizeEntries: true, logfileSize: 32 * 1024 * 1024 });
+/// @END_EXAMPLE_ARANGOSH_OUTPUT
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 static v8::Handle<v8::Value> JS_PropertiesWal (v8::Arguments const& argv) {
@@ -3920,7 +3975,32 @@ static v8::Handle<v8::Value> JS_PropertiesWal (v8::Arguments const& argv) {
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief flush the currently open WAL logfile
+/// @brief flushes the currently open WAL logfile
+/// @startDocuBlock walFlush
+/// `internal.wal.flush(waitForSync, waitForCollector)`
+///
+/// Flushes the write-ahead log. By flushing the currently active write-ahead
+/// logfile, the data in it can be transferred to collection journals and
+/// datafiles. This is useful to ensure that all data for a collection is
+/// present in the collection journals and datafiles, for example, when dumping
+/// the data of a collection.
+///
+/// The *waitForSync* option determines whether or not the operation should 
+/// block until the not-yet synchronized data in the write-ahead log was 
+/// synchronized to disk.
+///
+/// The *waitForCollector* operation can be used to specify that the operation
+/// should block until the data in the flushed log has been collected by the 
+/// write-ahead log garbage collector. Note that setting this option to *true* 
+/// might block for a long time if there are long-running transactions and 
+/// the write-ahead log garbage collector cannot finish garbage collection.
+///
+/// @EXAMPLES
+///
+/// @EXAMPLE_ARANGOSH_OUTPUT{WalFlush}
+///   require("internal").wal.flush();
+/// @END_EXAMPLE_ARANGOSH_OUTPUT
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 static v8::Handle<v8::Value> JS_FlushWal (v8::Arguments const& argv) {

js/actions/api-system.js

@@ -70,8 +70,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_server_role
 /// @brief returns the role of a server in a cluster
+/// @startDocuBlock JSF_get_admin_server_role
 ///
 /// @RESTHEADER{GET /_admin/server/role, Return role of a server in a cluster}
 ///
@@ -105,7 +105,40 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief flushes the WAL
+/// @brief flushes the write-ahead log
+/// @startDocuBlock JSF_put_admin_wal_flush
+///
+/// @RESTHEADER{PUT /_admin/wal/flush, Flushes the write-ahead log}
+///
+/// @RESTURLPARAMETERS
+///
+/// @RESTURLPARAM{waitForSync,boolean,optional}
+/// Whether or not the operation should block until the not-yet synchronized
+/// data in the write-ahead log was synchronized to disk.
+///
+/// @RESTURLPARAM{waitForCollector,boolean,optional}
+/// Whether or not the operation should block until the data in the flushed
+/// log has been collected by the write-ahead log garbage collector. Note that
+/// setting this option to *true* might block for a long time if there are
+/// long-running transactions and the write-ahead log garbage collector cannot
+/// finish garbage collection.
+///
+/// @RESTDESCRIPTION
+///
+/// Flushes the write-ahead log. By flushing the currently active write-ahead
+/// logfile, the data in it can be transferred to collection journals and
+/// datafiles. This is useful to ensure that all data for a collection is
+/// present in the collection journals and datafiles, for example, when dumping
+/// the data of a collection.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned if the operation succeeds.
+///
+/// @RESTRETURNCODE{405}
+/// is returned when an invalid HTTP method is used.
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 actions.defineHttp({
@@ -127,7 +160,100 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief gets or sets the WAL properties
+/// @brief configures the write-ahead log
+/// @startDocuBlock JSF_put_admin_wal_properties
+///
+/// @RESTHEADER{PUT /_admin/wal/properties, Configures the write-ahead log}
+///
+/// @RESTDESCRIPTION
+///
+/// Configures the behavior of the write-ahead log. The body of the request
+/// must be a JSON object with the following attributes:
+/// - *allowOversizeEntries*: whether or not operations that are bigger than a 
+///   single logfile can be executed and stored
+/// - *logfileSize*: the size of each write-ahead logfile
+/// - *historicLogfiles*: the maximum number of historic logfiles to keep
+/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB
+///   allocates in the background
+/// - *throttleWait*: the maximum wait time that operations will wait before
+///   they get aborted if case of write-throttling (in milliseconds)
+/// - *throttleWhenPending*: the number of unprocessed garbage-collection 
+///   operations that, when reached, will activate write-throttling. A value of
+///   *0* means that write-throttling will not be triggered.
+///
+/// Specifying any of the above attributes is optional. Not specified attributes
+/// will be ignored and the configuration for them will not be modified.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned if the operation succeeds.
+///
+/// @RESTRETURNCODE{405}
+/// is returned when an invalid HTTP method is used.
+/// @endDocuBlock
+///
+/// @EXAMPLES
+/// 
+/// @EXAMPLE_ARANGOSH_RUN{RestWalPropertiesPut}
+///     var url = "/_admin/wal/properties";
+///     var body = {
+///       logfileSize: 32 * 1024 * 1024,
+///       allowOversizeEntries: true
+///     };
+///     var response = logCurlRequest('PUT', url, JSON.stringify(body));
+/// 
+///     assert(response.code === 200);
+/// 
+///     logJsonResponse(response);
+/// @END_EXAMPLE_ARANGOSH_RUN
+/// @endDocuBlock
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief retrieves the configuration of the write-ahead log
+/// @startDocuBlock JSF_get_admin_wal_properties
+///
+/// @RESTHEADER{GET /_admin/wal/properties, Retrieves the configuration of the write-ahead log}
+///
+/// @RESTDESCRIPTION
+///
+/// Retrieves the configuration of the write-ahead log. The result is a JSON
+/// array with the following attributes:
+/// - *allowOversizeEntries*: whether or not operations that are bigger than a
+///   single logfile can be executed and stored
+/// - *logfileSize*: the size of each write-ahead logfile
+/// - *historicLogfiles*: the maximum number of historic logfiles to keep
+/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB
+///   allocates in the background
+/// - *syncInterval*: the interval for automatic synchronization of not-yet
+///   synchronized write-ahead log data (in milliseconds)
+/// - *throttleWait*: the maximum wait time that operations will wait before
+///   they get aborted if case of write-throttling (in milliseconds)
+/// - *throttleWhenPending*: the number of unprocessed garbage-collection 
+///   operations that, when reached, will activate write-throttling. A value of
+///   *0* means that write-throttling will not be triggered.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned if the operation succeeds.
+///
+/// @RESTRETURNCODE{405}
+/// is returned when an invalid HTTP method is used.
+/// @endDocuBlock
+///
+/// @EXAMPLES
+/// 
+/// @EXAMPLE_ARANGOSH_RUN{RestWalPropertiesGet}
+///     var url = "/_admin/wal/properties";
+///     var response = logCurlRequest('GET', url);
+/// 
+///     assert(response.code === 200);
+/// 
+///     logJsonResponse(response);
+/// @END_EXAMPLE_ARANGOSH_RUN
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 actions.defineHttp({
@@ -188,10 +314,10 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_routing_reloads
 /// @brief reloads the routing information
+/// @startDocuBlock JSF_get_admin_routing_reloads
 ///
-/// @RESTHEADER{POST /_admin/routing/reload, Reload routing collection}
+/// @RESTHEADER{POST /_admin/routing/reload, Reloads the routing information}
 ///
 /// @RESTDESCRIPTION
 ///
@@ -231,10 +357,10 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_modules_flush
 /// @brief flushes the modules cache
+/// @startDocuBlock JSF_get_admin_modules_flush
 ///
-/// @RESTHEADER{POST /_admin/modules/flush, Flush module cache}
+/// @RESTHEADER{POST /_admin/modules/flush, Flushes the modules cache}
 ///
 /// @RESTDESCRIPTION
 ///
@@ -261,8 +387,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_time
 /// @brief returns the system time
+/// @startDocuBlock JSF_get_admin_time
 ///
 /// @RESTHEADER{GET /_admin/time, Return system time}
 ///
@@ -289,8 +415,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_sleep
 /// @brief sleeps, this is useful for timeout tests
+/// @startDocuBlock JSF_get_admin_sleep
 ///
 /// @RESTHEADER{GET /_admin/sleep?duration=5, Sleep for 5 seconds}
 ///
@@ -322,8 +448,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_echo
 /// @brief returns the request
+/// @startDocuBlock JSF_get_admin_echo
 ///
 /// @RESTHEADER{GET /_admin/echo, Return current request}
 ///
@@ -357,8 +483,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_statistics
 /// @brief returns system status information for the server
+/// @startDocuBlock JSF_get_admin_statistics
 ///
 /// @RESTHEADER{GET /_admin/statistics, Read the statistics}
 ///
@@ -418,8 +544,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_statistics_description
 /// @brief returns statistics description
+/// @startDocuBlock JSF_get_admin_statistics_description
 ///
 /// @RESTHEADER{GET /_admin/statistics-description, Statistics description}
 /// 
@@ -789,8 +915,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_post_admin_test
 /// @brief executes one or multiple tests on the server
+/// @startDocuBlock JSF_post_admin_test
 ///
 /// @RESTHEADER{POST /_admin/test, Runs tests on the server}
 ///
@@ -848,8 +974,8 @@ actions.defineHttp({
 });
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSF_get_admin_execute
 /// @brief executes a JavaScript program on the server
+/// @startDocuBlock JSF_get_admin_execute
 ///
 /// @RESTHEADER{POST /_admin/execute, Execute program}
 ///