<commit_before>Write Concern
=============

The ``mongo_client`` and ``mongo_replset_client`` functions set a default write concern
at the top level specifying acknowledgements for writes.

In addition to reporting write errors, write concern also allows you to ensure
that your write are replicated to a particular number of servers to a set
of servers tagged with a given value.

Or for very-high write performance, write concern can specify non-blocking writes
without acknowledgment.
This is recommended only for cases that can tolerate the potential loss of a few writes
such as logging, analytics, etc.

The old ``mongo_connect`` and ``mongo_replset_connect`` functions have a default write concern
that is non-blocking without write acknowledgement.
They are deprecated and temporarily available for backward compatibility to smooth transition to
the ``mongo_client`` and ``mongo_replset_client`` functions.

Implementation and API
----------------------

Write concern is implemented by appending a call to the ``getlasterror``
command after each write.  You can certainly do this manually, but nearly all of the drivers
provide a write concern API for simplicty. To read about the options for ``getlasterror``,
and hence the options for write concern,
`see the MongoDB getlasterror docs <http://www.mongodb.org/display/DOCS/getLastError+Command>`_.

The MongoDB C driver supports write concern on two levels. You can set the write
concern on a ``mongo`` connection object, in which case that write concern level will
be used for every write. You can also specify a write concern for any individual
write operation (``mongo_insert()``, ``mongo_insert_batch()``, ``mongo_update()``,
or ``mongo_remove``). This will override any default write concern set on the
connection level.

Example
-------

.. code-block:: c

   #include <mongo.h>
   #include <stdio.h>

   #define ASSERT(x) \
    do{ \
        if(!(x)){ \
            printf("\nFailed ASSERT [%s] (%d):\n     %s\n\n", __FILE__,  __LINE__,  #x); \
            exit(1); \
        }\
    }while(0)

   int main() {
       mongo conn[1];
       mongo_write_concern write_concern[1];
       bson b[1];

       if( mongo_client( conn, "127.0.0.1", 27017 ) == MONGO_ERROR ) {
           printf( "Failed to connect!\n" );
           exit(1);
       }

       mongo_cmd_drop_collection( conn, "test", "foo", NULL );

       /* Initialize the write concern object.*/
       mongo_write_concern_init( write_concern );<commit_msg>CDRIVER-175 Implement default write acknowledgement with new MongoClient class write_concern doc tweak<commit_after>Write Concern
=============

The ``mongo_client`` and ``mongo_replset_client`` functions set a default write concern
at the top level specifying acknowledgements for writes.

In addition to reporting write errors, write concern also allows you to ensure
that your write are replicated to a particular number of servers to a set
of servers tagged with a given value.

Or for very-high write performance, write concern can specify non-blocking writes
without acknowledgment.
This is recommended only for cases that can tolerate the potential loss of a few writes
such as logging, analytics, etc.

The old ``mongo_connect`` and ``mongo_replset_connect`` functions have a default write concern
that is non-blocking without write acknowledgement.
They are deprecated and temporarily available for backward compatibility to smooth transition to
the ``mongo_client`` and ``mongo_replset_client`` functions.

Implementation and API
----------------------

Write concern is implemented by appending a call to the ``getlasterror``
command after each write.  You can certainly do this manually, but nearly all of the drivers
provide a write concern API for simplicty. To read about the options for ``getlasterror``,
and hence the options for write concern,
`see the MongoDB getlasterror docs <http://www.mongodb.org/display/DOCS/getLastError+Command>`_.

The MongoDB C driver supports write concern on two levels. You can set the write
concern on a ``mongo`` connection object, in which case that write concern level will
be used for every write. You can also specify a write concern for any individual
write operation (``mongo_insert()``, ``mongo_insert_batch()``, ``mongo_update()``,
or ``mongo_remove``). This will override any default write concern set on the
connection level.

The w parameter has the following specifics:

    -1       = do not call getLastError, suppress network errors
    0        = do not call getLastError
    1        = { getLastError : 1 }              - no "w" set
    2+       = { getLastError : 1, w : 2 }       - w : 3, etc.
    <string> = { getLastError: 1, w: <string> }

Example
-------

.. code-block:: c

   #include <mongo.h>
   #include <stdio.h>

   #define ASSERT(x) \
    do{ \
        if(!(x)){ \
            printf("\nFailed ASSERT [%s] (%d):\n     %s\n\n", __FILE__,  __LINE__,  #x); \
            exit(1); \
        }\
    }while(0)

   int main() {
       mongo conn[1];
       mongo_write_concern write_concern[1];
       bson b[1];

       if( mongo_client( conn, "127.0.0.1", 27017 ) == MONGO_ERROR ) {
           printf( "Failed to connect!\n" );
           exit(1);
       }

       mongo_cmd_drop_collection( conn, "test", "foo", NULL );

       /* Initialize the write concern object.*/
       mongo_write_concern_init( write_concern );
{'fraction_non_alphanumeric': 0.10185873605947955, 'fraction_numerical': 0.008550185873605948, 'mean_word_length': 3.353559870550162, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '966531', 'n_tokens_mistral': 1553, 'n_tokens_neox': 1475, 'n_words': 640}