DOCS-2304 param table: fsync

source/includes/note-disable-profiling-fsynclock.rst

@@ -1,10 +1,8 @@
-.. note::
-
-   The database cannot be locked with :method:`db.fsyncLock()` while
-   profiling is enabled.  You must disable profiling before locking
-   the database with :method:`db.fsyncLock()`.  Disable profiling
-   using :method:`db.setProfilingLevel()` as follows in the
-   :program:`mongo` shell:
+The database cannot be locked with :method:`db.fsyncLock()` while
+profiling is enabled.  You must disable profiling before locking
+the database with :method:`db.fsyncLock()`.  Disable profiling
+using :method:`db.setProfilingLevel()` as follows in the
+:program:`mongo` shell:
 
 .. code-block:: javascript
 

source/reference/command/fsync-field.yaml

@@ -0,0 +1,37 @@
+object:
+  name: fsync
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: fsync
+type: integer
+position: 1
+description: |
+  Enter "1" to apply :dbcommand:`fsync`.
+---
+object:
+  name: fsync
+  type: dbcommand
+field:
+  optional: true
+  type: field
+name: async
+type: Boolean
+position: 2
+description: |
+  Runs :dbcommand:`fsync` asynchronously. By default, the
+  :dbcommand:`fsync` operation is synchronous.
+---
+object:
+  name: fsync
+  type: dbcommand
+field:
+  optional: true
+  type: field
+name: lock
+type: Boolean
+position: 3
+description: |
+  Locks the database and blocks all write operations.
+...

source/reference/command/fsync.txt

@@ -4,95 +4,117 @@ fsync
 
 .. default-domain:: mongodb
 
+Definition
+----------
+
 .. dbcommand:: fsync
 
-   The :dbcommand:`fsync` command forces the :program:`mongod` process
-   to flush all pending writes to the storage layer. :program:`mongod`
-   is always writing data to the storage layer as applications write
-   more data. MongoDB guarantees that it will write all data to disk
-   within the :setting:`syncdelay` interval, which is 60 seconds by
-   default.
+   Forces the :program:`mongod` process to flush all pending writes from
+   the storage layer to disk. Optionally, you can lock the database and
+   block write operations while the flush occurs.
+
+   As applications write data, MongoDB records the data in the storage
+   layer and then writes the data to disk within the :setting:`syncdelay`
+   interval, which is 60 seconds by default. Run :dbcommand:`fsync` when
+   you want to flush writes to disk ahead of that interval.
+
+   The :dbcommand:`fsync` command has the following syntax:
 
    .. code-block:: javascript
 
-      { fsync: 1 }
+      { fsync: 1, async: <Boolean>, lock: <Boolean> }
 
-   The :dbcommand:`fsync` operation is synchronous by default, to run
-   :dbcommand:`fsync` asynchronously, use the following form:
+   The :dbcommand:`fsync` command has the following fields:
 
-   .. code-block:: javascript
+   .. include:: fsync-field.rst
 
-      { fsync: 1, async: true }
+Behavior
+--------
 
-   The connection will return immediately. You can check the output of
-   :method:`db.currentOp()` for the status of the :dbcommand:`fsync`
-   operation.
+An :dbcommand:`fsync` lock is only possible on *individual* shards of a
+sharded cluster, not on the entire cluster. To backup an entire sharded
+cluster, please see :doc:`/administration/backup-sharded-clusters` for
+more information.
 
-   The primary use of :dbcommand:`fsync` is to lock the database
-   during backup operations. This will flush all data to the data
-   storage layer and block all write operations until you unlock the
-   database. Consider the following command form:
+If your :program:`mongod` has :term:`journaling <journal>` enabled,
+consider using :ref:`another method <backup-with-journaling>` to create a
+back up of your data.
 
-   .. code-block:: javascript
+.. include:: /includes/note-disable-profiling-fsynclock.rst
 
-      { fsync: 1, lock: true }
+Examples
+--------
 
-   .. note::
+Run Asynchronously
+~~~~~~~~~~~~~~~~~~
 
-      You may continue to perform read operations on a database that
-      has a :dbcommand:`fsync` lock. However, after the first
-      write operation all subsequent read operations wait until
-      you unlock the database.
+The :dbcommand:`fsync` operation is synchronous by default To run
+:dbcommand:`fsync` asynchronously, use the ``async`` field set to
+``true``:
 
-   To check the state of the fsync lock, use
-   :method:`db.currentOp()`. Use the following JavaScript function in
-   the shell to test if the database is currently locked:
+.. code-block:: javascript
 
-   .. code-block:: javascript
+   { fsync: 1, async: true }
 
-      serverIsLocked = function () {
-                           var co = db.currentOp();
-                           if (co && co.fsyncLock) {
-                               return true;
-                           }
-                           return false;
-                       }
+The connection will return immediately. To view the status of the
+:dbcommand:`fsync` operation, check the output of
+:method:`db.currentOp()`.
 
-   After loading this function into your :program:`mongo` shell
-   session you can call it as follows:
+Lock the Database
+~~~~~~~~~~~~~~~~~
 
-   .. code-block:: javascript
+The primary use of :dbcommand:`fsync` is to lock the database during
+backup operations. This will flush all data to the data storage layer and
+block all write operations until you unlock the database.
 
-      serverIsLocked()
+To lock the database, use the ``lock`` field set to ``true``:
 
-   This function will return ``true`` if the :program:`mongod`
-   instance is currently
-   locked and ``false`` if the :program:`mongod` is not locked. To unlock the
-   :program:`mongod`, make a request for an unlock using the following operation:
+.. code-block:: javascript
 
-   .. code-block:: javascript
+   { fsync: 1, lock: true }
 
-      db.getSiblingDB("admin").$cmd.sys.unlock.findOne();
+You may continue to perform read operations on a database that has a
+:dbcommand:`fsync` lock. However, after the first write operation all
+subsequent read operations wait until you unlock the database.
 
-   In the :program:`mongo` shell, you may use the
-   :method:`db.fsyncLock()` and :method:`db.fsyncUnlock()` wrappers for
-   the :dbcommand:`fsync` lock and unlock process:
+Check Lock Status
+~~~~~~~~~~~~~~~~~
 
-   .. code-block:: javascript
+To check the state of the fsync lock, use :method:`db.currentOp()`. Use
+the following JavaScript function in the shell to test if the database is
+currently locked:
 
-      db.fsyncLock();
-      db.fsyncUnlock();
+.. code-block:: javascript
 
-   .. note::
+   serverIsLocked = function () {
+                        var co = db.currentOp();
+                        if (co && co.fsyncLock) {
+                            return true;
+                        }
+                        return false;
+                    }
 
-      An :dbcommand:`fsync` lock is only possible on *individual* shards of
-      a sharded cluster, not on the entire cluster. To backup an
-      entire sharded cluster, please see
-      :doc:`/administration/backup-sharded-clusters` for more
-      information.
+After loading this function into your :program:`mongo` shell session you
+can call it as follows:
 
-      If your :program:`mongod` has :term:`journaling <journal>`
-      enabled, consider using :ref:`another method
-      <backup-with-journaling>` to create a back up of your data.
+.. code-block:: javascript
 
-   .. include:: /includes/note-disable-profiling-fsynclock.rst
+   serverIsLocked()
+
+This function will return ``true`` if the :program:`mongod` instance is
+currently locked and ``false`` if the :program:`mongod` is not locked. To
+unlock the :program:`mongod`, make a request for an unlock using the
+following operation:
+
+.. code-block:: javascript
+
+   db.getSiblingDB("admin").$cmd.sys.unlock.findOne();
+
+Unlock the Database
+~~~~~~~~~~~~~~~~~~~
+
+To unlock the database, use :method:`db.fsyncUnlock()`:
+
+   .. code-block:: javascript
+
+      db.fsyncUnlock();