path: root/src/third_party/wiredtiger/src/include/wiredtiger_ext.h

/*-
 * Copyright (c) 2014-present MongoDB, Inc.
 * Copyright (c) 2008-2014 WiredTiger, Inc.
 *	All rights reserved.
 *
 * See the file LICENSE for redistribution information.
 */

#ifndef __WIREDTIGER_EXT_H_
#define __WIREDTIGER_EXT_H_

#include <wiredtiger.h>

#if defined(__cplusplus)
extern "C" {
#endif

#if !defined(SWIG)

/*!
 * @addtogroup wt_ext
 * @{
 */
typedef struct __wt_extension_spinlock WT_EXTENSION_SPINLOCK;
/*!
 * A placeholder data structure that allows for using the WiredTiger
 * spinlock implementation from within extensions.
 */
struct __wt_extension_spinlock {
    void *spinlock; /* Represents actual WiredTiger spinlock. */
};

/*!
 * Table of WiredTiger extension methods.
 *
 * This structure is used to provide a set of WiredTiger methods to extension
 * modules without needing to link the modules with the WiredTiger library.
 *
 * The extension methods may be used both by modules that are linked with
 * the WiredTiger library (for example, a data source configured using the
 * WT_CONNECTION::add_data_source method), and by modules not linked with the
 * WiredTiger library (for example, a compression module configured using the
 * WT_CONNECTION::add_compressor method).
 *
 * To use these functions:
 * - include the wiredtiger_ext.h header file,
 * - declare a variable which references a WT_EXTENSION_API structure, and
 * - initialize the variable using WT_CONNECTION::get_extension_api method.
 *
 * @snippet ex_data_source.c WT_EXTENSION_API declaration
 *
 * The following code is from the sample compression module, where compression
 * extension functions are configured in the extension's entry point:
 *
 * @snippet nop_compress.c WT_COMPRESSOR initialization structure
 * @snippet nop_compress.c WT_COMPRESSOR initialization function
 */
struct __wt_extension_api {
/* !!! To maintain backwards compatibility, this structure is append-only. */
#if !defined(DOXYGEN)
    /*
     * Private fields.
     */
    WT_CONNECTION *conn; /* Enclosing connection */
#endif
    /*!
     * Insert an error message into the WiredTiger error stream.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param fmt a printf-style format specification
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION_API err_printf
     */
    int (*err_printf)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *fmt, ...);

    /*!
     * Insert a message into the WiredTiger message stream.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param fmt a printf-style format specification
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION_API msg_printf
     */
    int (*msg_printf)(WT_EXTENSION_API *, WT_SESSION *session, const char *fmt, ...);

    /*!
     * Return information about an error as a string.
     *
     * @snippet ex_data_source.c WT_EXTENSION_API strerror
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param error a return value from a WiredTiger function
     * @returns a string representation of the error
     */
    const char *(*strerror)(WT_EXTENSION_API *, WT_SESSION *session, int error);

    /*!
     * Map a Windows system error code to a POSIX 1003.1/ANSI C error.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param windows_error a Windows system error code
     * @returns a Unix-style error code
     *
     * @snippet ex_data_source.c WT_EXTENSION_API map_windows_error
     */
    int (*map_windows_error)(WT_EXTENSION_API *wt_api, WT_SESSION *session, uint32_t windows_error);

    /*!
     * Allocate short-term use scratch memory.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param bytes the number of bytes of memory needed
     * @returns A valid memory reference on success or NULL on error
     *
     * @snippet ex_data_source.c WT_EXTENSION_API scr_alloc
     */
    void *(*scr_alloc)(WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t bytes);

    /*!
     * Free short-term use scratch memory.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param ref a memory reference returned by WT_EXTENSION_API::scr_alloc
     *
     * @snippet ex_data_source.c WT_EXTENSION_API scr_free
     */
    void (*scr_free)(WT_EXTENSION_API *, WT_SESSION *session, void *ref);

    /*!
     * Configure the extension collator method.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param uri the URI of the handle being configured
     * @param config the configuration information passed to an application
     * @param collatorp the selector collator, if any
     * @param ownp set if the collator terminate method should be called
     * when no longer needed
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION collator config
     */
    int (*collator_config)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *uri,
      WT_CONFIG_ARG *config, WT_COLLATOR **collatorp, int *ownp);

    /*!
     * The extension collator method.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param collator the collator (or NULL if none available)
     * @param first first item
     * @param second second item
     * @param[out] cmp set less than 0 if \c first collates less than
     * \c second, set equal to 0 if \c first collates equally to \c second,
     * set greater than 0 if \c first collates greater than \c second
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION collate
     */
    int (*collate)(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_COLLATOR *collator,
      WT_ITEM *first, WT_ITEM *second, int *cmp);

    /*!
     * Return the value of a configuration key.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param config the configuration information passed to an application
     * @param key configuration key string
     * @param value the returned value
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION config_get
     */
    int (*config_get)(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_CONFIG_ARG *config,
      const char *key, WT_CONFIG_ITEM *value);

    /*!
     * Return the value of a configuration key from a string.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param config the configuration string
     * @param key configuration key string
     * @param value the returned value
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION config_get
     */
    int (*config_get_string)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *config,
      const char *key, WT_CONFIG_ITEM *value);

    /*!
     * Create a handle that can be used to parse or create configuration strings
     * compatible with the WiredTiger API.
     * @param wt_api the extension handle
     * @param session the session handle to be used for error reporting
     * @param config the configuration string being parsed. The string must
     *     remain valid for the lifetime of the parser handle.
     * @param len the number of valid bytes in \c config
     * @param[out] config_parserp A pointer to the newly opened handle
     * @errors
     */
    int (*config_parser_open)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *config,
      size_t len, WT_CONFIG_PARSER **config_parserp);

    /*!
     * Create a handle that can be used to parse or create configuration strings
     * compatible with the WiredTiger API.
     * @param wt_api the extension handle
     * @param session the session handle to be used for error reporting
     * @param config the configuration argument passed to the extension
     * @param[out] config_parserp A pointer to the newly opened handle
     * @errors
     */
    int (*config_parser_open_arg)(WT_EXTENSION_API *wt_api, WT_SESSION *session,
      WT_CONFIG_ARG *config, WT_CONFIG_PARSER **config_parserp);

    /*!
     * Get the file system abstraction used by WiredTiger.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param file_system the returned file system handle.
     * @errors
     * If called from an extension's initialization routine, this may
     * return WT_NOTFOUND if the file system has not yet been established.
     *
     * @snippet ex_data_source.c WT_EXTENSION metadata insert
     */
    int (*file_system_get)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_FILE_SYSTEM **file_system);

    /*!
     * Insert a row into the metadata if it does not already exist.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param key row key
     * @param value row value
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION metadata insert
     */
    int (*metadata_insert)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value);

    /*!
     * Remove a row from the metadata.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param key row key
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION metadata remove
     */
    int (*metadata_remove)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key);

    /*!
     * Return a row from the metadata.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param key row key
     * @param [out] valuep the row value
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION metadata search
     */
    int (*metadata_search)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, char **valuep);

    /*!
     * Update a row in the metadata by either inserting a new record or
     * updating an existing record.
     *
     * @param wt_api the extension handle
     * @param session the session handle (or NULL if none available)
     * @param key row key
     * @param value row value
     * @errors
     *
     * @snippet ex_data_source.c WT_EXTENSION metadata update
     */
    int (*metadata_update)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value);

    /*!
     * Pack a structure into a buffer. Deprecated in favor of stream
     * based pack and unpack API. See WT_EXTENSION_API::pack_start for
     * details.
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param buffer a pointer to a packed byte array
     * @param size the number of valid bytes in the buffer
     * @param format the data format, see @ref packing
     * @errors
     */
    int (*struct_pack)(WT_EXTENSION_API *wt_api, WT_SESSION *session, void *buffer, size_t size,
      const char *format, ...);

    /*!
     * Calculate the size required to pack a structure. Deprecated in
     * favor of stream based pack and unpack API.
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param sizep a location where the number of bytes needed for the
     * matching call to WT_EXTENSION_API::struct_pack is returned
     * @param format the data format, see @ref packing
     * @errors
     */
    int (*struct_size)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t *sizep, const char *format, ...);

    /*!
     * Unpack a structure from a buffer. Deprecated in favor of stream
     * based pack and unpack API. See WT_EXTENSION_API::unpack_start for
     * details.
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param buffer a pointer to a packed byte array
     * @param size the number of valid bytes in the buffer
     * @param format the data format, see @ref packing
     * @errors
     */
    int (*struct_unpack)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const void *buffer,
      size_t size, const char *format, ...);

    /*
     * Streaming pack/unpack API.
     */
    /*!
     * Start a packing operation into a buffer.
     * See ::wiredtiger_pack_start for details.
     *
     * @param session the session handle
     * @param format the data format, see @ref packing
     * @param buffer a pointer to memory to hold the packed data
     * @param size the size of the buffer
     * @param[out] psp the new packing stream handle
     * @errors
     */
    int (*pack_start)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *format,
      void *buffer, size_t size, WT_PACK_STREAM **psp);

    /*!
     * Start an unpacking operation from a buffer.
     * See ::wiredtiger_unpack_start for details.
     *
     * @param session the session handle
     * @param format the data format, see @ref packing
     * @param buffer a pointer to memory holding the packed data
     * @param size the size of the buffer
     * @param[out] psp the new packing stream handle
     * @errors
     */
    int (*unpack_start)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *format,
      const void *buffer, size_t size, WT_PACK_STREAM **psp);

    /*!
     * Close a packing stream.
     *
     * @param ps the packing stream handle
     * @param[out] usedp the number of bytes in the buffer used by the
     * stream
     * @errors
     */
    int (*pack_close)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, size_t *usedp);

    /*!
     * Pack an item into a packing stream.
     *
     * @param ps the packing stream handle
     * @param item an item to pack
     * @errors
     */
    int (*pack_item)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, WT_ITEM *item);

    /*!
     * Pack a signed integer into a packing stream.
     *
     * @param ps the packing stream handle
     * @param i a signed integer to pack
     * @errors
     */
    int (*pack_int)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, int64_t i);

    /*!
     * Pack a string into a packing stream.
     *
     * @param ps the packing stream handle
     * @param s a string to pack
     * @errors
     */
    int (*pack_str)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, const char *s);

    /*!
     * Pack an unsigned integer into a packing stream.
     *
     * @param ps the packing stream handle
     * @param u an unsigned integer to pack
     * @errors
     */
    int (*pack_uint)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, uint64_t u);

    /*!
     * Unpack an item from a packing stream.
     *
     * @param ps the packing stream handle
     * @param item an item to unpack
     * @errors
     */
    int (*unpack_item)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, WT_ITEM *item);

    /*!
     * Unpack a signed integer from a packing stream.
     *
     * @param ps the packing stream handle
     * @param[out] ip the unpacked signed integer
     * @errors
     */
    int (*unpack_int)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, int64_t *ip);

    /*!
     * Unpack a string from a packing stream.
     *
     * @param ps the packing stream handle
     * @param[out] sp the unpacked string
     * @errors
     */
    int (*unpack_str)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, const char **sp);

    /*!
     * Unpack an unsigned integer from a packing stream.
     *
     * @param ps the packing stream handle
     * @param[out] up the unpacked unsigned integer
     * @errors
     */
    int (*unpack_uint)(WT_EXTENSION_API *wt_api, WT_PACK_STREAM *ps, uint64_t *up);

    /*!
     * @copydoc wiredtiger_version
     */
    const char *(*version)(int *majorp, int *minorp, int *patchp);

    /*!
     * Initialize a spinlock
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param spinlock the extension spinlock
     * @param name the name for the spinlock
     *
     */
    int (*spin_init)(WT_EXTENSION_API *wt_api, WT_EXTENSION_SPINLOCK *spinlock, const char *name);

    /*!
     * Destroy a spinlock
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param spinlock the extension spinlock
     *
     */
    void (*spin_destroy)(WT_EXTENSION_API *wt_api, WT_EXTENSION_SPINLOCK *spinlock);

    /*!
     * Spin until the lock is acquired.
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param spinlock the extension spinlock
     *
     */
    void (*spin_lock)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_EXTENSION_SPINLOCK *spinlock);

    /*!
     * Release the spinlock.
     *
     * @param wt_api the extension handle
     * @param session the session handle
     * @param spinlock the extension spinlock
     *
     */
    void (*spin_unlock)(
      WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_EXTENSION_SPINLOCK *spinlock);
};

/*!
 * @typedef WT_CONFIG_ARG
 *
 * A configuration object passed to some extension interfaces.  This is an
 * opaque type: configuration values can be queried using
 * WT_EXTENSION_API::config_get.
 */

/*! @} */
#endif /* SWIG */

#if defined(__cplusplus)
}
#endif
#endif /* __WIREDTIGER_EXT_H_ */