diff --git a/source/includes/fact-eval-lock.rst b/source/includes/fact-eval-lock.rst new file mode 100644 index 00000000000..0f957f8bdcc --- /dev/null +++ b/source/includes/fact-eval-lock.rst @@ -0,0 +1,19 @@ +.. eval-command-nolock + +By default, :dbcommand:`eval` takes a global write lock before +evaluating the JavaScript function. This means that :dbcommand:`eval` +blocks all other read and write operations to the database while the +:dbcommand:`eval` operation runs. Set ``nolock`` to ``true`` to ensure +that :dbcommand:`eval` does not take this global write lock before +evaluating the function. The flag does not impact whether the +JavaScript code itself takes a write lock. + +.. eval-method-lock + +The :method:`db.eval()` method takes a global write lock by default +before executing the JavaScript function. This means that +:method:`db.eval()` blocks all other read and write operations to the +database while the :method:`db.eval()` operation runs. You can, +however, use the :dbcommand:`eval` command, instead of the +:method:`db.eval()` method, with the ``nolock`` flag to ``true``. See +:dbcommand:`eval` command for more details. diff --git a/source/reference/command/eval.txt b/source/reference/command/eval.txt index 768b5e3176c..90d08977a35 100644 --- a/source/reference/command/eval.txt +++ b/source/reference/command/eval.txt @@ -22,7 +22,7 @@ eval The command contains the following fields: - :param JavaScript function: + :field JavaScript function: A JavaScript function. @@ -43,7 +43,7 @@ eval // ... } - :param arguments: + :field arguments: A list of arguments to pass to the JavaScript ``function`` if the function accepts arguments. Omit if the ``function`` does @@ -54,19 +54,10 @@ eval An array of corresponding arguments to the ``function``. Omit ``args`` if the ``function`` does not take arguments. - :field boolean nolock: + :field boolean nolock: Optional. - Optional. Specifies whether to disable the write lock. By - default, :dbcommand:`eval` takes a write lock. There are - circumstances where the :dbcommand:`eval` executes a strictly - read-only operation that does not need to block other - operations. If ``nolock`` is ``true``, the - :dbcommand:`eval` does not take a write lock. - - .. warning:: - - Do not disable the write lock if the function may modify - the contents of the database in any way. + .. include:: /includes/fact-eval-lock.rst + :end-before: eval-method-lock Consider the following example which uses :dbcommand:`eval` to perform an increment and calculate the average on the server: @@ -111,8 +102,8 @@ eval }, "eliot", 5 ); - You cannot pass the ``nolock`` flag to the :method:`db.eval()` - in the :program:`mongo` shell. + The :method:`db.eval()` method does not support the ``nolock`` + option. If you want to use the server's interpreter, you must run :dbcommand:`eval`. Otherwise, the :program:`mongo` shell's @@ -144,15 +135,13 @@ eval .. warning:: - - The :method:`db.eval()` operation takes a write lock by - default. This means that :dbcommand:`eval` blocks all other - read and write operations to the database while the - :dbcommand:`eval` operation runs. You can, however, disable - the lock by setting the ``nolock`` flag to ``true`` if the - :dbcommand:`eval` performs a strictly read-only operation. + - .. include:: /includes/fact-eval-lock.rst + :end-before: eval-method-lock - :dbcommand:`eval` also takes a JavaScript lock. +.. modified in 2.4 version, the JavaScript lock is up to and including version 2.2 + - Do not use :dbcommand:`eval` for long running operations as :dbcommand:`eval` blocks all other operations. Consider using :doc:`other server side code execution options diff --git a/source/reference/method/db.eval.txt b/source/reference/method/db.eval.txt index 11681870d28..99ca6bc092b 100644 --- a/source/reference/method/db.eval.txt +++ b/source/reference/method/db.eval.txt @@ -11,7 +11,9 @@ db.eval() The :method:`db.eval()` provides the ability to run JavaScript code on the MongoDB server. It is a :program:`mongo` shell wrapper around - the :dbcommand:`eval` command. + the :dbcommand:`eval` command. However, unlike the :dbcommand:`eval` + command, the :method:`db.eval()` method does not support the + ``nolock`` option. The method accepts the following parameters: @@ -91,17 +93,12 @@ db.eval() .. warning:: - - The :method:`db.eval()` operation takes a write lock by - default. This means that :method:`db.eval()` blocks all other - read and write operations to the database while - the :method:`db.eval()` operation runs. However, if you are using the - :dbcommand:`eval` command using :method:`db.runCommand()` - rather than the helper, you can disable the lock by setting - the ``nolock`` flag to ``true`` if the :dbcommand:`eval` - performs a strictly read-only operation. - - - :method:`db.eval()` also takes a JavaScript lock which blocks - all + - .. include:: /includes/fact-eval-lock.rst + :start-after: eval-method-lock + + - :method:`db.eval()` also takes a JavaScript lock. + +.. modified in 2.4 version, the JavaScript lock is up to and including version 2.2 - Do not use :method:`db.eval()` for long running operations, as :method:`db.eval()` blocks all other operations. Consider using