Merge to port changes made to the manual, while in write-concern holding pattern.

bin/makefile_builder.py

@@ -1,4 +1,7 @@
+#!/usr/bin/python
+
 # Copyright 2012 10gen, Inc.
+# Author: Sam Kleinman (tychoish)
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,25 +15,98 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-class MakefileBuilder(object):
-    def __init__(self, makefile=None):
-        self.builder = { '_all' : [] }
 
-        if makefile is not None and type(makefile) is list:
-            self.makefile = makefile
+def print_output(list):
+    for line in list:
+        print(line)
+
+def write_file(list, filename):
+    with open(filename, 'w') as f:
+        for line in list:
+            f.write(line + '\n')
+
+
+class BuildFileError(Exception):
+    def __init__(self, msg=None):
+        self.msg = msg
+
+    def __str__(self):
+        if self.msg is None:
+            return "Error in handling BuildFile."
         else:
-            self.makefile = self.builder['_all'] = []
+            return "Error: " + self.msg
 
-    def add_to_builder(self, data, block):
-        if block is '_all':
+class BuildFile(object):
+    def __init__(self, buildfile=None):
+        self.builder = { '_all' : [] }
+        self.buildfile = self.builder['_all']
+
+        if buildfile is None:
             pass
+        elif type(buildfile) is list:
+            for line in buildfile:
+                if type(line) is list:
+                    raise BuildFileError('Cannot instantiate BuildFile with nested list.')
+                    break
+                else:
+                    self.builder['_all'].append(line)
         else:
-            self.makefile.append(data)
+            raise BuildFileError('Instantiated BuildFile object with malformed argument.')
 
-        if block in self.builder:
-            self.builder[block].append(data)
+    # the following method is used internally to constrcd uct and
+    # maintain the internal representation of the buildfile.
+
+    def _add_to_builder(self, data, block):
+        if type(data) is not str:
+            raise BuildFileError('Added malformed data to BuildFile.')
         else:
-            self.builder[block] = [data]
+            if block is '_all':
+                pass
+            else:
+                self.buildfile.append(data)
+
+            if block in self.builder:
+                self.builder[block].append(data)
+            else:
+                self.builder[block] = [data]
+
+    # The following methods produce output for public use.
+
+    def get_block(self, block='_all'):
+        return self.builder[block]
+
+    def print_content(self, block_order=['_all']):
+        output = []
+
+        for block in block_order:
+            output.append(self.builder[block])
+
+        output = [item for sublist in output for item in sublist]
+        print_output(output)
+
+    def print_block(self, block='all'):
+        print_output(self.builder[block])
+
+    def write(self, filename, block_order=['_all']):
+        output = []
+
+        for block in block_order:
+            output.append(self.builder[block])
+
+        output = [item for sublist in output for item in sublist]
+        write_file(output, filename)
+
+    def write_block(self, filename, block='_all'):
+        write_file(self.builder[block], filename)
+
+
+class MakefileBuilder(BuildFile):
+    def __init__(self, makefile=None):
+        super(MakefileBuilder, self).__init__(makefile)
+        self.makefile = self.buildfile
+
+    # The following two methods allow more direct interaction with the
+    # internal representation of the makefile than the other methods.
 
     def block(self, block):
         if block in self.builder:
@@ -40,56 +116,43 @@ def block(self, block):
             self.section_break(block, block)
 
     def raw(self, lines, block='_all'):
-        self.add_to_builder(lines, block)
+        self._add_to_builder(lines, block)
+
+    # The following methods constitute the 'public' interface for
+    # building makefile.
 
     def section_break(self, name, block='_all'):
-        self.add_to_builder('\n\n########## ' + name + ' ##########\n', block)
+        self._add_to_builder('\n\n########## ' + name + ' ##########', block)
 
     def comment(self, comment, block='_all'):
-        self.add_to_builder('\n# ' + comment + '\n', block)
+        self._add_to_builder('\n# ' + comment, block)
 
     def newline(self, n=1, block='_all'):
         for i in range(n):
-            self.add_to_builder('\n', block)
+            self._add_to_builder('\n', block)
 
     def target(self, target, dependency=None, block='_all'):
-        if dependency is None: 
-            self.add_to_builder(target + ':' + '\n', block)
-        else: 
-            self.add_to_builder(target + ':' + dependency + '\n', block)
-            
+        if dependency is None:
+            self._add_to_builder(target + ':', block)
+        else:
+            self._add_to_builder(target + ':' + dependency, block)
+
     def var(self, variable, value, block='_all'):
-        self.add_to_builder(variable + ' = ' + value + '\n', block)
+        self._add_to_builder(variable + ' = ' + value, block)
 
     def append_var(self, variable, value, block='_all'):
-        self.add_to_builder(variable + ' += ' + value + '\n', block)
+        self._add_to_builder(variable + ' += ' + value, block)
 
     def job(self, job, display=False, block='_all'):
         if display is True:
-            o = '\t' + job + '\n'
+            o = '\t' + job
         else:
-            o = '\t@' + job + '\n'
+            o = '\t@' + job
 
-        self.add_to_builder(o, block)
+        self._add_to_builder(o, block)
 
     def message(self, message, block='_all'):
-        self.add_to_builder('\t@echo ' + message + '\n', block)
+        m = 'echo ' + message
+        self.job(job=m, display=False, block=block)
 
     msg = message
-
-    def print_content(self, block_order=['_all']):
-        o = []
-        for block in block_order:
-            o.append(self.builder[block])
-            o = [item for sublist in o for item in sublist]
-        for line in o:
-            print(line.rstrip())
-
-    def write(self, filename, block_order=['_all']):
-        o = []
-        for block in block_order:
-            o.append(self.builder[block])
-            o = [item for sublist in o for item in sublist]
-        with open(filename, 'w') as f:
-            for line in o:
-                f.write(line)

source/administration/replica-sets.txt

@@ -87,10 +87,11 @@ To configure a member as secondary-only, set its
 situation. For more information on priority levels, see
 :ref:`replica-set-node-priority`.
 
+.. include:: /includes/note-rs-conf-array-index.rst
+
 As an example of modifying member priorities, assume a four-member
-replica set with member ``_id`` values of: ``0``, ``1``, ``2``, and
-``3``. Use the following sequence of operations in the :program:`mongo`
-shell to modify member priorities:
+replica set. Use the following sequence of operations in the
+:program:`mongo` shell to modify member priorities:
 
 .. code-block:: javascript
 
@@ -101,9 +102,9 @@ shell to modify member priorities:
    cfg.members[3].priority = 2
    rs.reconfig(cfg)
 
-This sets the following:
+This configures the set, with the following priority settings: 
 
-- Member ``0`` to a priority of ``0`` so that it can never become :term:`primary`.
+- The first (i.e. )Member ``0`` to a priority of ``0`` so that it can never become :term:`primary`.
 
 - Member ``1`` to a priority of ``0.5``, which makes it less likely to
   become primary than other members but doesn't prohibit the
@@ -156,17 +157,19 @@ operations in the :program:`mongo` shell:
    cfg.members[0].hidden = true
    rs.reconfig(cfg)
 
-After re-configuring the set, the member with the ``_id`` of ``0``
-has a priority of ``0`` so that it cannot become primary. The
-other members in the set will not advertise the hidden member in the
-:dbcommand:`isMaster` or :method:`db.isMaster()` output.
+After re-configuring the set, the first member of the set in the
+:data:`members <rs.conf.members>` array will have a priority of ``0``
+so that it cannot become primary. The other members in the set will
+not advertise the hidden member in the :dbcommand:`isMaster` or
+:method:`db.isMaster()` output.
 
 .. note::
 
    You must send the :method:`rs.reconfig()` command to a set member
-   that *can* become :term:`primary`. In the above example, if you issue
-   the :method:`rs.reconfig()` operation to the member with the ``_id``
-   of ``0``, the operation fails.
+   that *can* become :term:`primary`. In the above example, if you
+   issue the :method:`rs.reconfig()` operation to a member with a
+   :data:`priority <members.[n].priority>` of ``0`` the operation will
+   fail. 
 
 .. note::
 
@@ -224,8 +227,8 @@ following sequence of operations in the :program:`mongo` shell:
    cfg.members[0].slaveDelay = 3600
    rs.reconfig(cfg)
 
-After the replica set reconfigures, the set member with the ``_id`` of
-``0`` has a priority of ``0`` and cannot become :term:`primary`. The :data:`slaveDelay <members[n].slaveDelay>` value
+After the replica set reconfigures, the first member of the set in the
+:data:`members <rs.conf.members>` array will have a priority of ``0`` and cannot become :term:`primary`. The :data:`slaveDelay <members[n].slaveDelay>` value
 delays both replication and the member's :term:`oplog` by 3600 seconds (1
 hour). Setting :data:`slaveDelay <members[n].slaveDelay>` to a
 non-zero value also sets :data:`hidden <members[n].hidden>` to
@@ -313,13 +316,14 @@ command sequence in the :program:`mongo` shell.
    cfg.members[5].votes = 0
    rs.reconfig(cfg)
 
-This sequence gives ``0`` votes to set members with the ``_id``
-values of ``3``, ``4``, and ``5``. This setting allows the set to
-elect these members as :term:`primary` but does not allow them to
-vote in elections. If you have three non-voting members, you can add
-three additional voting members to your set. Place voting members so that
-your designated primary or primaries can reach a majority of votes in
-the event of a network partition.
+This sequence gives ``0`` votes to the fourth, fifth, and sixth
+members of the set according to the order of the :data:`members
+<rs.conf.members>` array in the output of :method:`rs.conf()`.  This
+setting allows the set to elect these members as :term:`primary` but
+does not allow them to vote in elections. If you have three non-voting
+members, you can add three additional voting members to your
+set. Place voting members so that your designated primary or primaries
+can reach a majority of votes in the event of a network partition.
 
 .. note::
 
@@ -466,11 +470,14 @@ the :program:`mongo` shell:
 The first operation uses :method:`rs.conf()` to set the local variable
 ``cfg`` to the contents of the current replica set configuration, which
 is a :term:`document`. The next three operations change the
-:data:`members[n].priority` value in the ``cfg`` document for
-:data:`members[n]._id` of ``0``, ``1``, or ``2``. The final operation
+:data:`members[n].priority` value in the ``cfg`` document for the
+first three members configured in the :data:`members
+<rs.conf.members>` array. The final operation
 calls :method:`rs.reconfig()` with the argument of ``cfg`` to initialize
 the new configuration.
 
+.. include:: /includes/note-rs-conf-array-index.rst
+
 If a member has :data:`members[n].priority` set to ``0``, it is
 ineligible to become :term:`primary` and will not seek
 election. :ref:`Hidden members <replica-set-hidden-members>`,

source/core/sharding.txt

@@ -160,7 +160,7 @@ A :term:`sharded cluster` has the following components:
      in a sharded cluster via the :program:`mongos` instances as below.
      If you connect directly to a :program:`mongod` in a sharded cluster
      you will see its fraction of cluster's data. The data on any
-     given shard may be somewhat random: MongoDB provides no grantee
+     given shard may be somewhat random: MongoDB provides no guarantee
      that any two contiguous chunks will reside on a single shard.
 
 - One or more :program:`mongos` instances.

source/includes/note-rs-conf-array-index.rst

@@ -0,0 +1,10 @@
+.. note:: 
+
+   When updating the replica configuration object, address all members
+   of the set using the index value in the array. The array index
+   begins with ``0``. Do not confuse this index value with the value
+   of the :data:`_id <members[n]._id` field in each document in the
+   :data:`members <rs.conf.members>` array.
+
+   The :data:`_id <members[n]._id` rarely corresponds to the array
+   index.

source/includes/warning-terminating-operations.rst

@@ -0,0 +1,5 @@
+.. warning:: 
+
+   Terminate running operations with extreme caution. Only use
+   :method:`db.killOp()` to terminate operations initiated by clients
+   and *do not* terminate internal database operations.