diff options
Diffstat (limited to 'src/include/wiredtiger.in')
| -rw-r--r-- | src/include/wiredtiger.in | 175 |
1 files changed, 107 insertions, 68 deletions
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, |