diff options
| -rw-r--r-- | dist/s_string.ok | 3 | ||||
| -rw-r--r-- | docs/src/collators.dox | 16 | ||||
| -rw-r--r-- | docs/src/compression.dox | 10 | ||||
| -rw-r--r-- | docs/src/extending.dox | 27 | ||||
| -rw-r--r-- | docs/src/install.dox | 4 | ||||
| -rw-r--r-- | docs/src/introduction.dox | 18 | ||||
| -rw-r--r-- | docs/src/schema.dox | 2 | ||||
| -rw-r--r-- | docs/src/using.dox | 10 | ||||
| -rw-r--r-- | examples/c/ex_all.c | 114 | ||||
| -rw-r--r-- | examples/c/ex_extending.c | 6 | ||||
| -rw-r--r-- | src/include/wiredtiger.in | 175 |
11 files changed, 217 insertions, 168 deletions
diff --git a/dist/s_string.ok b/dist/s_string.ok index 16353faa1c2..a54c65e03aa 100644 --- a/dist/s_string.ok +++ b/dist/s_string.ok @@ -345,6 +345,8 @@ negint newname nl nlpo +nocase +nop notsup notyet np @@ -363,6 +365,7 @@ posint posix pre prepended +presize printf priv pthread diff --git a/docs/src/collators.dox b/docs/src/collators.dox deleted file mode 100644 index e05189f6bd2..00000000000 --- a/docs/src/collators.dox +++ /dev/null @@ -1,16 +0,0 @@ -/*! @page collators Collators - -@section extending_example Code samples - -The code below is taken from the complete example program -@ex_ref{ex_extending.c}. - -@snippet ex_extending.c case insensitive comparator - -@snippet ex_extending.c n character comparator - -@snippet ex_extending.c add collator nocase - -@snippet ex_extending.c add collator prefix10 - -*/ diff --git a/docs/src/compression.dox b/docs/src/compression.dox index 1d8a13e5b1c..c2223f0a404 100644 --- a/docs/src/compression.dox +++ b/docs/src/compression.dox @@ -42,14 +42,6 @@ Verify that the snappy part of the test passes and was not skipped. @section custom Custom compression engines -To build your own compressor, use one of the compressors in <code>ext/compressors</code> as a template. <code>nop_compress</code> is a simple compressor that passes through data unchanged, and is a reasonable starting point. - -Compressors must implement the WT_COMPRESSOR interface, and will use WT_CONNECTION::add_compressor to register their interface; see @ex_ref{ex_all.c} as an example. In WT_COMPRESSOR, the WT_COMPRESSOR::compress and WT_COMPRESSOR::decompress callbacks must be specified, and WT_COMPRESSOR::pre_size is optional. - -WT_COMPRESSOR::compress is given a source buffer and a destination buffer, by default of the same size. If the callback can compress the buffer to a smaller size in the destination, it does so, sets the <code>compression_failed</code> return to 0 and returns 0. If the compression does not produce a smaller result, the callback sets the <code>compression_failed</code> return to 1 and returns 0. If another error occurs, it returns an errno or WiredTiger error code. - -WT_COMPRESSOR::decompress is given a source buffer and a destination buffer. The contents are switched from <code>compress</code>: the source buffer is the compressed value, and the destination buffer is sized to be the original size. If the callback successfully decompresses the source buffer to the destination buffer, it returns 0. If an error occurs, it returns an errno or WiredTiger error code. The source buffer that WT_COMPRESSOR::decompress is given may have a size that is rounded up from the size originally produced by WT_COMPRESSOR::compress, with the remainder of the buffer set to zeroes. Most compressors do not care about this difference if the size to be decompressed can be implicitly discovered from the compressed data. If your compressor cares, you may need to allocate space for, and store, the actual size in the compressed buffer. See the source code for the snappy compressor as an example of this. - -WT_COMPRESSOR::pre_size is an optional callback that, given the source buffer and size, produces the size of the destination buffer to be given to WT_COMPRESSOR::compress. This is useful for compressors that assume that the output buffer is sized for the worst case and thus no overrun checks are made. If your compressor works like this, WT_COMPRESSOR::pre_size will need to be defined. See the source code for the snappy compressor as an example. However, if your compressor detects and avoids overruns against its target buffer, you will not need to define WT_COMPRESSOR::pre_size. When WT_COMPRESSOR::pre_size is set to null, the destination buffer is sized the same as the source buffer. This is always sufficient, since a compression result that is larger than the source buffer is discarded by WiredTiger. +WiredTiger may be extended by adding custom compression engines; see @ref WT_COMPRESSOR for more information. */ diff --git a/docs/src/extending.dox b/docs/src/extending.dox deleted file mode 100644 index bb9f4d9049f..00000000000 --- a/docs/src/extending.dox +++ /dev/null @@ -1,27 +0,0 @@ -/*! @page extending Extending WiredTiger - -@section modules Loadable modules - -@todo describe loadable modules - -@section adding_cursor_types Adding cursor types - -- @subpage stat_desc - -@todo explain how to add cursor types - -@section custom_collators Collators - -- @subpage collators - -@todo explain custom collators - -@section custom_compressors Compressors - -- @subpage compression - -@section extractors Custom field extractors - -@todo explain custom extractors - - */ diff --git a/docs/src/install.dox b/docs/src/install.dox index e7fe78463d8..ec824257647 100644 --- a/docs/src/install.dox +++ b/docs/src/install.dox @@ -105,7 +105,7 @@ Configure WiredTiger to sleep and wait for a debugger to attach on failure. @par \c --enable-bzip2 Configure WiredTiger for <a href="http://www.bzip.org/">bzip2</a> -compression. +compression; see @ref compression for more information. @par \c --enable-debug Configure WiredTiger for debugging, including building with the @@ -121,7 +121,7 @@ Build the WiredTiger <a href="http://www.python.org">Python</a> API. @par \c --enable-snappy Configure WiredTiger for <a href="http://code.google.com/p/snappy/">snappy</a> -compression. +compression; see @ref compression for more information. @par \c --enable-verbose Configure WiredTiger to support the \c verbose configuration string to diff --git a/docs/src/introduction.dox b/docs/src/introduction.dox index c58d3d73bab..c0e07e7ad60 100644 --- a/docs/src/introduction.dox +++ b/docs/src/introduction.dox @@ -1,8 +1,8 @@ /*! @mainpage Reference Guide -The WiredTiger Data Store is an extensible platform for data management. -This documentation describes the programming interface to WiredTiger -used by developers to construct applications. +WiredTiger is an extensible platform for data management. This +documentation describes the programming interface to WiredTiger used by +developers to construct applications. We follow SQL terminology: a database is set of tables managed together. Tables consist of rows, where each row is a key and its associated @@ -25,16 +25,4 @@ For more information about using WiredTiger, see: - @subpage command_line\n -- @subpage extending\n - -- @ref wt_ext "WiredTiger extensions API reference manual" - -- @subpage security - -- @subpage file_formats - -- @subpage name_space - -- @subpage signals - */ diff --git a/docs/src/schema.dox b/docs/src/schema.dox index c9256d8b378..2a3d51704a0 100644 --- a/docs/src/schema.dox +++ b/docs/src/schema.dox @@ -123,7 +123,7 @@ natural integer ordering under the default collator. See @subpage packing for details of WiredTiger's packing format. -WiredTiger can also be extended with @ref collators "custom collators". +WiredTiger can also be extended with @ref WT_COLLATOR. @section schema_data_access Columns in key and values diff --git a/docs/src/using.dox b/docs/src/using.dox index de8326243fc..1faf7146961 100644 --- a/docs/src/using.dox +++ b/docs/src/using.dox @@ -4,11 +4,19 @@ This section explains how to use WiredTiger by developing a sequence of example programs: - @subpage basic_api -- @subpage home - @subpage config_strings - @subpage schema - @subpage cursors - @subpage threads - @subpage transactions + +Additional Notes: + +- @subpage home +- @subpage security +- @subpage file_formats +- @subpage name_space +- @subpage signals - @subpage tuning + */ diff --git a/examples/c/ex_all.c b/examples/c/ex_all.c index d67dc8917bf..938d592ad2e 100644 --- a/examples/c/ex_all.c +++ b/examples/c/ex_all.c @@ -258,10 +258,8 @@ cursor_search_near(WT_CURSOR *cursor) int session_ops(WT_SESSION *session) { - WT_CURSOR *c1, *c2; - int ret; - - c1 = c2 = NULL; + unsigned long mypid = 0; + int exact, ret; cursor_ops(session); @@ -270,40 +268,80 @@ session_ops(WT_SESSION *session) "key_format=S,value_format=S"); /*! [Create a table] */ - ret = session->rename(session, "table:old", "table:new", NULL); + /*! [session checkpoint] */ + ret = session->checkpoint(session, NULL); + /*! [session checkpoint] */ + /*! [session drop] */ ret = session->drop(session, "table:mytable", NULL); + /*! [session drop] */ + + /*! [session dumpfile] */ + ret = session->dumpfile(session, "file:myfile", NULL); + /*! [session dumpfile] */ + + /*! [session msg_printf] */ + ret = session->msg_printf(session, "process pid %lu", mypid); + /*! [session msg_printf] */ + + /*! [session rename] */ + ret = session->rename(session, "table:old", "table:new", NULL); + /*! [session rename] */ + + /*! [session salvage] */ + ret = session->salvage(session, "table:mytable", NULL); + /*! [session salvage] */ + /*! [session sync] */ ret = session->sync(session, "table:mytable", NULL); + /*! [session sync] */ + /*! [session truncate] */ ret = session->truncate(session, "table:mytable", NULL, NULL, NULL); + /*! [session truncate] */ { - /*! [Truncate cursor] */ + /*! [session range truncate] */ WT_CURSOR *start, *stop; - start = c1; - stop = c2; + start->set_key(start, "June01"); + ret = start->search_near(start, &exact); + + stop->set_key(stop, "June30"); + ret = stop->search_near(stop, &exact); + ret = session->truncate(session, NULL, start, stop, NULL); - /*! [Truncate cursor] */ + /*! [session range truncate] */ } + /*! [session upgrade] */ + ret = session->upgrade(session, "table:mytable", NULL); + /*! [session upgrade] */ + + /*! [session verify] */ ret = session->verify(session, "table:mytable", NULL); + /*! [session verify] */ + /*! [session begin transaction] */ ret = session->begin_transaction(session, NULL); + /*! [session begin transaction] */ + /*! [session commit transaction] */ ret = session->commit_transaction(session, NULL); + /*! [session commit transaction] */ + /*! [session rollback transaction] */ ret = session->rollback_transaction(session, NULL); + /*! [session rollback transaction] */ - ret = session->checkpoint(session, NULL); - + /*! [session close] */ ret = session->close(session, NULL); + /*! [session close] */ return (ret); } -/*! [Implement WT_CURSOR_TYPE] */ +/*! [WT_CURSOR_TYPE size] */ static int my_cursor_size(WT_CURSOR_TYPE *ctype, const char *obj, size_t *sizep) { @@ -313,7 +351,9 @@ my_cursor_size(WT_CURSOR_TYPE *ctype, const char *obj, size_t *sizep) *sizep = sizeof (WT_CURSOR); return (0); } +/*! [WT_CURSOR_TYPE size] */ +/*! [WT_CURSOR_TYPE init] */ static int my_init_cursor(WT_CURSOR_TYPE *ctype, WT_SESSION *session, const char *obj, WT_CURSOR *old_cursor, const char *config, @@ -329,22 +369,25 @@ my_init_cursor(WT_CURSOR_TYPE *ctype, WT_SESSION *session, return (0); } -/*! [Implement WT_CURSOR_TYPE] */ +/*! [WT_CURSOR_TYPE init] */ int add_cursor_type(WT_CONNECTION *conn) { int ret; - /*! [Register a new cursor type] */ + /*! [WT_CURSOR_TYPE register] */ static WT_CURSOR_TYPE my_ctype = { my_cursor_size, my_init_cursor }; ret = conn->add_cursor_type(conn, NULL, &my_ctype, NULL); - /*! [Register a new cursor type] */ + /*! [WT_CURSOR_TYPE register] */ return (ret); } /*! [Implement WT_COLLATOR] */ +/* + * A simple example of the collator API: compare the keys as strings. + */ static int my_compare(WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *value1, const WT_ITEM *value2, int *cmp) @@ -370,15 +413,18 @@ add_collator(WT_CONNECTION *conn) { int ret; - /*! [Register a new collator] */ + /*! [WT_COLLATOR register] */ static WT_COLLATOR my_collator = { my_compare }; ret = conn->add_collator(conn, "my_collator", &my_collator, NULL); - /*! [Register a new collator] */ + /*! [WT_COLLATOR register] */ return (ret); } -/*! [Implement WT_COMPRESSOR] */ +/*! [WT_COMPRESSOR compress] */ +/* + * A simple compression example that passes data through unchanged. + */ static int my_compress(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, @@ -398,7 +444,12 @@ my_compress(WT_COMPRESSOR *compressor, WT_SESSION *session, *result_lenp = src_len; return (0); } +/*! [WT_COMPRESSOR compress] */ +/*! [WT_COMPRESSOR decompress] */ +/* + * A simple decompression example that passes data through unchanged. + */ static int my_decompress(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, @@ -416,7 +467,12 @@ my_decompress(WT_COMPRESSOR *compressor, WT_SESSION *session, *result_lenp = src_len; return (0); } +/*! [WT_COMPRESSOR decompress] */ +/*! [WT_COMPRESSOR presize] */ +/* + * A simple pre-size example that returns the source length. + */ static int my_pre_size(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, @@ -430,23 +486,23 @@ my_pre_size(WT_COMPRESSOR *compressor, WT_SESSION *session, *result_lenp = src_len; return (0); } -/*! [Implement WT_COMPRESSOR] */ +/*! [WT_COMPRESSOR presize] */ int add_compressor(WT_CONNECTION *conn) { int ret; - /*! [Register a new compressor] */ + /*! [WT_COMPRESSOR register] */ static WT_COMPRESSOR my_compressor = { my_compress, my_decompress, my_pre_size }; ret = conn->add_compressor(conn, "my_compress", &my_compressor, NULL); - /*! [Register a new compressor] */ + /*! [WT_COMPRESSOR register] */ return (ret); } -/*! [Implement WT_EXTRACTOR] */ +/*! [WT_EXTRACTOR] */ static int my_extract(WT_EXTRACTOR *extractor, WT_SESSION *session, const WT_ITEM *key, const WT_ITEM *value, @@ -460,18 +516,18 @@ my_extract(WT_EXTRACTOR *extractor, WT_SESSION *session, *result = *value; return (0); } -/*! [Implement WT_EXTRACTOR] */ +/*! [WT_EXTRACTOR] */ int add_extractor(WT_CONNECTION *conn) { int ret; - /*! [Register a new extractor] */ + /*! [WT_EXTRACTOR register] */ static WT_EXTRACTOR my_extractor; my_extractor.extract = my_extract; ret = conn->add_extractor(conn, "my_extractor", &my_extractor, NULL); - /*! [Register a new extractor] */ + /*! [WT_EXTRACTOR register] */ return (ret); } @@ -481,15 +537,21 @@ connection_ops(WT_CONNECTION *conn) { int ret; + /*! [conn load extension] */ ret = conn->load_extension(conn, "my_extension.dll", NULL); + /*! [conn load extension] */ add_cursor_type(conn); add_collator(conn); add_extractor(conn); + /*! [conn close] */ ret = conn->close(conn, NULL); + /*! [conn close] */ - printf("The home is %s\n", conn->get_home(conn)); + /*! [conn get_home] */ + printf("The database home is %s\n", conn->get_home(conn)); + /*! [conn get_home] */ /*! [is_new] */ if (conn->is_new(conn)) { diff --git a/examples/c/ex_extending.c b/examples/c/ex_extending.c index ce4058d691a..24ba398bb37 100644 --- a/examples/c/ex_extending.c +++ b/examples/c/ex_extending.c @@ -17,7 +17,7 @@ const char *home = "WT_TEST"; /*! [case insensitive comparator] */ -/* Case insensitive comparator. */ +/* A simple case insensitive comparator. */ static int __compare_nocase(WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *v1, const WT_ITEM *v2, int *cmp) @@ -37,8 +37,8 @@ static WT_COLLATOR nocasecoll = { __compare_nocase }; /*! [n character comparator] */ /* - * Comparator that only compares the first N characters in strings. This - * has associated data, so we need to extend WT_COLLATOR. + * Comparator that only compares the first N prefix characters of the string. + * This has associated data, so we need to extend WT_COLLATOR. */ typedef struct { WT_COLLATOR iface; diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in index c18497f4696..f8a556b32be 100644 --- a/src/include/wiredtiger.in +++ b/src/include/wiredtiger.in @@ -59,8 +59,8 @@ extern "C" { #endif /*! @defgroup wt WiredTiger API - * The commonly-used functions, handles and methods that applications use to - * access and manage data with WiredTiger. + * The functions, handles and methods applications use to access and manage + * data with WiredTiger. * * @{ */ @@ -434,8 +434,7 @@ struct __wt_session { * including rolling any active transactions and closing any cursors * that remain open in the session. * - * @dontinclude ex_all.c - * @skipline session->close + * @snippet ex_all.c session close * * @param session the session handle * @configempty{session.close, see dist/api_data.py} @@ -634,8 +633,7 @@ struct __wt_session { /*! Drop (delete) an object. * - * @dontinclude ex_all.c - * @skipline ->drop + * @snippet ex_all.c session drop * * @param session the session handle * @param name the URI of the object to drop, such as \c "table:stock" @@ -650,8 +648,7 @@ struct __wt_session { /*! Rename an object. @notyet{session->rename} * - * @dontinclude ex_all.c - * @skipline ->rename + * @snippet ex_all.c session rename * * @param session the session handle * @param oldname the current URI of the object, such as \c "table:old" @@ -676,8 +673,7 @@ struct __wt_session { * Files are rebuilt in place, the salvage method overwrites the * existing files. * - * @dontinclude ex_all.c - * @skipline ->salvage + * @snippet ex_all.c session salvage * * @param session the session handle * @param name the URI of the file or table to salvage @@ -697,8 +693,7 @@ struct __wt_session { * use by other threads of control may not be written until all open * session handles for the table are closed). * - * @dontinclude ex_all.c - * @skipline ->sync + * @snippet ex_all.c session sync * * @param session the session handle * @param name the URI of the file or table to sync @@ -710,10 +705,9 @@ struct __wt_session { /*! Truncate a file, table or a cursor range. * - * @dontinclude ex_all.c - * @skipline ->truncate + * @snippet ex_all.c session truncate * - * @snippet ex_all.c Truncate cursor + * @snippet ex_all.c session range truncate * * @param session the session handle * @param name the URI of the file or table to truncate @@ -734,8 +728,7 @@ struct __wt_session { * * Upgrade upgrades a file, or the files of which a table is comprised. * - * @dontinclude ex_all.c - * @skipline ->upgrade + * @snippet ex_all.c session upgrade * * @param session the session handle * @param name the URI of the file or table to upgrade @@ -751,8 +744,7 @@ struct __wt_session { * comprised, have been corrupted. The WT_SESSION::salvage method * can be used to repair a corrupted file, * - * @dontinclude ex_all.c - * @skipline ->verify + * @snippet ex_all.c session verify * * @param session the session handle * @param name the URI of the file or table to verify @@ -777,8 +769,7 @@ struct __wt_session { * * @todo describe nested transactions / savepoints * - * @dontinclude ex_all.c - * @skipline ->begin_transaction + * @snippet ex_all.c session begin transaction * * @param session the session handle * @configstart{session.begin_transaction, see dist/api_data.py} @@ -806,8 +797,7 @@ struct __wt_session { * * Ignored if no transaction is in progress. * - * @dontinclude ex_all.c - * @skipline ->commit_transaction + * @snippet ex_all.c session commit transaction * * @param session the session handle * @configempty{session.commit_transaction, see dist/api_data.py} @@ -822,8 +812,7 @@ struct __wt_session { * * Ignored if no transaction is in progress. * - * @dontinclude ex_all.c - * @skipline ->rollback_transaction + * @snippet ex_all.c session rollback transaction * * @param session the session handle * @configempty{session.rollback_transaction, see dist/api_data.py} @@ -834,8 +823,7 @@ struct __wt_session { /*! Flush the cache and/or the log and optionally archive log files. * @notyet{checkpoint} * - * @dontinclude ex_all.c - * @skipline ->checkpoint + * @snippet ex_all.c session checkpoint * * @param session the session handle * @configstart{session.checkpoint, see dist/api_data.py} @@ -868,11 +856,10 @@ struct __wt_session { * The specified file is displayed in a non-portable debugging mode to * the application's standard output. * - * @dontinclude ex_all.c - * @skipline ->dumpfile + * @snippet ex_all.c session dumpfile * * @param session the session handle - * @param name the URI of the table to verify + * @param name the URI of the file to dump * @configempty{session.dumpfile, see dist/api_data.py} * @errors */ @@ -881,8 +868,7 @@ struct __wt_session { /*! Send a string to the message handler for debugging. * - * @dontinclude ex_all.c - * @skipline ->msg_printf + * @snippet ex_all.c session msg_printf * * @param session the session handle * @param fmt a printf-like format specification @@ -906,8 +892,7 @@ struct __wt_session { struct __wt_connection { /*! Load an extension. * - * @dontinclude ex_all.c - * @skipline ->load_extension + * @snippet ex_all.c conn load extension * * @param connection the connection handle * @param path the filename of the extension module @@ -925,12 +910,10 @@ struct __wt_connection { /*! Add a new type of cursor. @notyet{custom cursors} * - * @dontinclude ex_all.c - * * The application must first implement the WT_CURSOR_TYPE interface - * and then register the implementation with WiredTiger as follows: + * and then register the implementation with WiredTiger: * - * @snippet ex_all.c Register a new cursor type + * @snippet ex_all.c WT_CURSOR_TYPE register * * @param connection the connection handle * @param prefix the prefix for location strings passed to @@ -946,9 +929,9 @@ struct __wt_connection { /*! Add a custom collation function. @notyet{custom collation} * * The application must first implement the WT_COLLATOR interface and - * then register the implementation with WiredTiger as follows: + * then register the implementation with WiredTiger: * - * @snippet ex_all.c Register a new collator + * @snippet ex_all.c WT_COLLATOR register * * @param connection the connection handle * @param name the name of the collation to be used in calls to @@ -963,9 +946,9 @@ struct __wt_connection { /*! Add a compression function. * * The application must first implement the WT_COMPRESSOR interface - * and then register the implementation with WiredTiger as follows: + * and then register the implementation with WiredTiger: * - * @snippet ex_all.c Register a new compressor + * @snippet ex_all.c WT_COMPRESSOR register * * @param connection the connection handle * @param name the name of the compression function to be used in calls @@ -981,9 +964,9 @@ struct __wt_connection { * @notyet{custom extractors} * * The application must first implement the WT_EXTRACTOR interface and - * then register the implementation with WiredTiger as follows: + * then register the implementation with WiredTiger: * - * @snippet ex_all.c Register a new extractor + * @snippet ex_all.c WT_EXTRACTOR register * * @param connection the connection handle * @param name the name of the extractor to be used in calls to @@ -999,8 +982,7 @@ struct __wt_connection { * * Any open sessions will be closed. * - * @dontinclude ex_all.c - * @skipline conn->close + * @snippet ex_all.c conn close * * @param connection the connection handle * @configempty{connection.close, see dist/api_data.py} @@ -1010,8 +992,7 @@ struct __wt_connection { /*! The home directory of the connection. * - * @dontinclude ex_all.c - * @skipline ->get_home + * @snippet ex_all.c conn get_home * * @param connection the connection handle * @returns a pointer to a string naming the home directory @@ -1111,7 +1092,6 @@ int wiredtiger_open(const char *home, /*! Return information about an error as a string; wiredtiger_strerror is a * superset of the ISO C99/POSIX 1003.1-2001 function strerror. * - * @dontinclude ex_all.c * @snippet ex_all.c Display an error * * @param err a return value from a WiredTiger, C library or POSIX function @@ -1268,20 +1248,21 @@ const char *wiredtiger_version(int *majorp, int *minorp, int *patchp); /*! @} */ /*! @defgroup wt_ext WiredTiger Extension API - * The functions and interfaces that applications use to customize and extend - * the behavior of WiredTiger. - * + * The functions and interfaces applications use to customize and extend the + * behavior of WiredTiger. * @{ */ /*! * The interface implemented by applications to provide custom ordering of - * records. The following is a simple example of the collator API: - * - * @snippet ex_all.c Implement WT_COLLATOR + * records. * * Applications register their implementation with WiredTiger by calling * WT_CONNECTION::add_collator. + * + * @snippet ex_extending.c add collator nocase + * + * @snippet ex_extending.c add collator prefix10 */ struct __wt_collator { /*! Callback to compare keys. @@ -1290,6 +1271,12 @@ struct __wt_collator { * 0 if <code>key1 == key2</code>, * 1 if <code>key1 > key2</code>. * @returns zero for success, non-zero to indicate an error. + * + * @snippet ex_all.c Implement WT_COLLATOR + * + * @snippet ex_extending.c case insensitive comparator + * + * @snippet ex_extending.c n character comparator */ int (*compare)(WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *key1, const WT_ITEM *key2, int *cmp); @@ -1297,16 +1284,30 @@ struct __wt_collator { /*! * The interface implemented by applications to provide custom compression. - * The following is a simple example of the compressor API: * - * @snippet ex_all.c Implement WT_COMPRESSOR + * Compressors must implement the WT_COMPRESSOR interface: the + * WT_COMPRESSOR::compress and WT_COMPRESSOR::decompress callbacks must be + * specified, and WT_COMPRESSOR::pre_size is optional. To build your own + * compressor, use one of the compressors in \c ext/compressors as a template: + * \c ext/nop_compress is a simple compressor that passes through data + * unchanged, and is a reasonable starting point. * * Applications register their implementation with WiredTiger by calling * WT_CONNECTION::add_compressor. + * + * @snippet ex_all.c WT_COMPRESSOR register */ struct __wt_compressor { /*! Callback to compress a chunk of data. * + * WT_COMPRESSOR::compress is given a source buffer and a destination + * buffer, by default of the same size. If the callback can compress + * the buffer to a smaller size in the destination, it does so, sets + * the \c compression_failed return to 0 and returns 0. If compression + * does not produce a smaller result, the callback sets the + * \c compression_failed return to 1 and returns 0. If another + * error occurs, it returns an errno or WiredTiger error code. + * * On entry, \c src will point to memory, with the length of the memory * in \c src_len. After successful completion, the callback should * return \c 0 and set \c result_lenp to the number of bytes required @@ -1324,6 +1325,8 @@ struct __wt_compressor { * @param[out] compression_failed non-zero if compression did not * decrease the length of the data (compression may not have completed) * @returns zero for success, non-zero to indicate an error. + * + * @snippet ex_all.c WT_COMPRESSOR compress */ int (*compress)(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, @@ -1332,6 +1335,21 @@ struct __wt_compressor { /*! Callback to decompress a chunk of data. * + * WT_COMPRESSOR::decompress is given a source buffer and a destination + * buffer. The contents are switched from \c compress: the + * source buffer is the compressed value, and the destination buffer is + * sized to be the original size. If the callback successfully + * decompresses the source buffer to the destination buffer, it returns + * 0. If an error occurs, it returns an errno or WiredTiger error code. + * The source buffer that WT_COMPRESSOR::decompress is given may have a + * size that is rounded up from the size originally produced by + * WT_COMPRESSOR::compress, with the remainder of the buffer set to + * zeroes. Most compressors do not care about this difference if the + * size to be decompressed can be implicitly discovered from the + * compressed data. If your compressor cares, you may need to allocate + * space for, and store, the actual size in the compressed buffer. See + * the source code for the included snappy compressor for an example. + * * On entry, \c src will point to memory, with the length of the memory * in \c src_len. After successful completion, the callback should * return \c 0 and set \c result_lenp to the number of bytes required @@ -1346,6 +1364,8 @@ struct __wt_compressor { * @param[in] dst_len the length of the destination buffer * @param[out] result_lenp the length of the decompressed data * @returns zero for success, non-zero to indicate an error. + * + * @snippet ex_all.c WT_COMPRESSOR decompress */ int (*decompress)(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, @@ -1354,6 +1374,20 @@ struct __wt_compressor { /*! Callback to size a destination buffer for compression * + * WT_COMPRESSOR::pre_size is an optional callback that, given the + * source buffer and size, produces the size of the destination buffer + * to be given to WT_COMPRESSOR::compress. This is useful for + * compressors that assume that the output buffer is sized for the + * worst case and thus no overrun checks are made. If your compressor + * works like this, WT_COMPRESSOR::pre_size will need to be defined. + * See the source code for the snappy compressor for an example. + * However, if your compressor detects and avoids overruns against its + * target buffer, you will not need to define WT_COMPRESSOR::pre_size. + * When WT_COMPRESSOR::pre_size is set to NULL, the destination buffer + * is sized the same as the source buffer. This is always sufficient, + * since a compression result that is larger than the source buffer is + * discarded by WiredTiger. + * * If not NULL, this callback is called before each call to * WT_COMPRESS::compress to determine the size of the destination * buffer to provide. If the callback is NULL, the destination @@ -1371,6 +1405,8 @@ struct __wt_compressor { * @param[in] src_len the length of the data to compress * @param[out] result_lenp the required destination buffer size * @returns zero for success, non-zero to indicate an error. + * + * @snippet ex_all.c WT_COMPRESSOR presize */ int (*pre_size)(WT_COMPRESSOR *compressor, WT_SESSION *session, uint8_t *src, size_t src_len, size_t *result_lenp); @@ -1380,16 +1416,14 @@ struct __wt_compressor { * Applications can extend WiredTiger by providing new implementations of the * WT_CURSOR class. * - * The following is a simple example of the WT_CURSOR API: - * - * @snippet ex_all.c Implement WT_CURSOR_TYPE + * <b>Thread safety:</b> WiredTiger may invoke methods on the WT_CURSOR_TYPE + * interface from multiple threads concurrently. It is the responsibility of + * the implementation to protect any shared data. * * Applications register their implementation with WiredTiger by calling * WT_CONNECTION::add_cursor_type. * - * <b>Thread safety:</b> WiredTiger may invoke methods on the WT_CURSOR_TYPE - * interface from multiple threads concurrently. It is the responsibility of - * the implementation to protect any shared data. + * @snippet ex_all.c WT_CURSOR_TYPE register */ struct __wt_cursor_type { /*! Callback to determine how much space to allocate for a cursor. @@ -1398,11 +1432,16 @@ struct __wt_cursor_type { * WT_CURSOR implementation. * * @errors + * + * @snippet ex_all.c WT_CURSOR_TYPE size */ int (*cursor_size)(WT_CURSOR_TYPE *ctype, const char *obj, size_t *sizep); - /*! Callback to initialize a cursor. */ + /*! Callback to initialize a cursor. + * + * @snippet ex_all.c WT_CURSOR_TYPE init + */ int (*init_cursor)(WT_CURSOR_TYPE *ctype, WT_SESSION *session, const char *obj, WT_CURSOR *old_cursor, const char *config, WT_CURSOR *new_cursor); @@ -1412,17 +1451,17 @@ struct __wt_cursor_type { * The interface implemented by applications to provide custom extraction of * index keys or column group values. * - * The following is a simple example of the WT_EXTRACTOR API: - * - * @snippet ex_all.c Implement WT_EXTRACTOR - * * Applications register implementations with WiredTiger by calling * WT_CONNECTION::add_extractor. + * + * @snippet ex_all.c WT_EXTRACTOR register */ struct __wt_extractor { /*! Callback to extract a value for an index or column group. * * @errors + * + * @snippet ex_all.c WT_EXTRACTOR */ int (*extract)(WT_EXTRACTOR *extractor, WT_SESSION *session, const WT_ITEM *key, const WT_ITEM *value, |