From c715a40f5355625426411f512b7db1dd98d396e1 Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 7 Jan 2013 15:58:24 -0500 Subject: [PATCH 1/2] DOCS-954 eval() helper and nolock DOCS-954 db.eval() method and nolock option DOCS-954 incorporate Scott's feedback incorporate Tad's comments DOCS-954 eval and lock --- source/reference/command/eval.txt | 41 ++++++++++++++--------------- source/reference/method/db.eval.txt | 27 ++++++++++--------- 2 files changed, 35 insertions(+), 33 deletions(-) diff --git a/source/reference/command/eval.txt b/source/reference/command/eval.txt index 768b5e3176c..4aad23a3dc7 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 @@ -56,17 +56,11 @@ eval :field boolean nolock: - 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. + Optional. By default, :dbcommand:`eval` takes a global write lock + before evaluating the JavaScript function. If ``nolock`` is + ``true``, the :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. Consider the following example which uses :dbcommand:`eval` to perform an increment and calculate the average on the server: @@ -111,8 +105,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 +138,20 @@ 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. + - The :dbcommand:`eval` command takes a global write lock by + default before executing the JavaScript function. This means + that :dbcommand:`eval` blocks all other read and write + operations to the database while the :dbcommand:`eval` + operation runs. You can, however, set the ``nolock`` flag to + ``true`` to prevent the :dbcommand:`eval` command from taking a + global write lock before executing the JavaScript function. The + flag does not impact whether the JavaScript code itself takes + a write 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..02bfb403a79 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,18 @@ 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 + - 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. + + - :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 From a9964532283b0e842f41fcd685aae0921f0ba9ea Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 19 Feb 2013 15:27:52 -0500 Subject: [PATCH 2/2] DOCS-954 eval and locks --- source/includes/fact-eval-lock.rst | 19 +++++++++++++++++++ source/reference/command/eval.txt | 20 +++++--------------- source/reference/method/db.eval.txt | 12 +++--------- 3 files changed, 27 insertions(+), 24 deletions(-) create mode 100644 source/includes/fact-eval-lock.rst 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 4aad23a3dc7..90d08977a35 100644 --- a/source/reference/command/eval.txt +++ b/source/reference/command/eval.txt @@ -54,13 +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. By default, :dbcommand:`eval` takes a global write lock - before evaluating the JavaScript function. If ``nolock`` is - ``true``, the :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. + .. 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: @@ -138,15 +135,8 @@ eval .. warning:: - - The :dbcommand:`eval` command takes a global write lock by - default before executing the JavaScript function. This means - that :dbcommand:`eval` blocks all other read and write - operations to the database while the :dbcommand:`eval` - operation runs. You can, however, set the ``nolock`` flag to - ``true`` to prevent the :dbcommand:`eval` command from taking a - global write lock before executing the JavaScript function. The - flag does not impact whether the JavaScript code itself takes - a write lock. + - .. include:: /includes/fact-eval-lock.rst + :end-before: eval-method-lock - :dbcommand:`eval` also takes a JavaScript lock. diff --git a/source/reference/method/db.eval.txt b/source/reference/method/db.eval.txt index 02bfb403a79..99ca6bc092b 100644 --- a/source/reference/method/db.eval.txt +++ b/source/reference/method/db.eval.txt @@ -93,15 +93,9 @@ db.eval() .. warning:: - - 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. - + - .. 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