WT_EXTENSION_API Struct Reference

Table of WiredTiger extension methods. More...

Public Attributes
int(*	err_printf )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *fmt,...)
	Insert an error message into the WiredTiger error stream. More...
int(*	msg_printf )(WT_EXTENSION_API *, WT_SESSION *session, const char *fmt,...)
	Insert a message into the WiredTiger message stream. More...
const char *(*	strerror )(int err)
	Return information about an error as a string; the strerror method is a superset of the ISO C99/POSIX 1003.1-2001 function strerror. More...
void *(*	scr_alloc )(WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t bytes)
	Allocate short-term use scratch memory. More...
void(*	scr_free )(WT_EXTENSION_API *, WT_SESSION *session, void *ref)
	Free short-term use scratch memory. More...
int(*	collator_config )(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_CONFIG_ARG *config)
	Configure the extension collator method. More...
int(*	collate )(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_ITEM *first, WT_ITEM *second, int *cmp)
	The extension collator method. More...
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 string. More...
int(*	config_strget )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *config, const char *key, WT_CONFIG_ITEM *value)
	Return the value of a configuration string. More...
int(*	config_scan_begin )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *str, size_t len, WT_CONFIG_SCAN **scanp)
	Return the list entries of a configuration string value. More...
int(*	config_scan_end )(WT_EXTENSION_API *wt_api, WT_CONFIG_SCAN *scan)
	Release any resources allocated by WT_EXTENSION_API::config_scan_begin. More...
int(*	config_scan_next )(WT_EXTENSION_API *wt_api, WT_CONFIG_SCAN *scan, WT_CONFIG_ITEM *key, WT_CONFIG_ITEM *value)
	Return the next key/value pair from a config string scan. More...
int(*	metadata_insert )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value)
	Insert a row into the metadata if it does not already exist. More...
int(*	metadata_remove )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key)
	Remove a row from the metadata. More...
int(*	metadata_search )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char **valuep)
	Return a row from the metadata. More...
int(*	metadata_update )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value)
	Update a row in the metadata by either inserting a new record or updating an existing record. More...
int(*	struct_pack )(WT_EXTENSION_API *wt_api, WT_SESSION *session, void *buffer, size_t size, const char *format,...)
	Pack a structure into a buffer. More...
int(*	struct_size )(WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t *sizep, const char *format,...)
	Calculate the size required to pack a structure. More...
int(*	struct_unpack )(WT_EXTENSION_API *wt_api, WT_SESSION *session, const void *buffer, size_t size, const char *format,...)
	Unpack a structure from a buffer. More...
uint64_t(*	transaction_id )(WT_EXTENSION_API *wt_api, WT_SESSION *session)
	Return the current transaction ID. More...
int(*	transaction_isolation_level )(WT_EXTENSION_API *wt_api, WT_SESSION *session)
	Return the current transaction's isolation level; returns one of WT_TXN_ISO_READ_COMMITTED, WT_TXN_ISO_READ_UNCOMMITTED, or WT_TXN_ISO_SNAPSHOT. More...
int(*	transaction_notify )(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_TXN_NOTIFY *notify)
	Request notification of transaction resolution by specifying a function to be called when the session's current transaction is either committed or rolled back. More...
uint64_t(*	transaction_oldest )(WT_EXTENSION_API *wt_api)
	Return the oldest transaction ID not yet visible to a running transaction. More...
int(*	transaction_visible )(WT_EXTENSION_API *wt_api, WT_SESSION *session, uint64_t transaction_id)
	Return if the current transaction can see the given transaction ID. More...

Detailed Description

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.

#include <wiredtiger_ext.h>

static WT_EXTENSION_API *wt_api;

static void
my_data_source_init(WT_CONNECTION *connection)
{
        wt_api = connection->get_extension_api(connection);
}

The following code is from the sample compression module, where compression extension functions are configured in the extension's entry point:

/* Local compressor structure. */
typedef struct {
        WT_COMPRESSOR compressor;               /* Must come first */

        WT_EXTENSION_API *wt_api;               /* Extension API */
} NOP_COMPRESSOR;

/*
 * A simple shared library compression example.
 */
int
wiredtiger_extension_init(WT_CONNECTION *connection, WT_CONFIG_ARG *config)
{
        NOP_COMPRESSOR *nop_compressor;

        (void)config;                           /* Unused parameters */

        if ((nop_compressor = calloc(1, sizeof(NOP_COMPRESSOR))) == NULL)
                return (errno);

        /*
         * Allocate a local compressor structure, with a WT_COMPRESSOR structure
         * as the first field, allowing us to treat references to either type of
         * structure as a reference to the other type.
         *
         * This could be simplified if only a single database is opened in the
         * application, we could use a static WT_COMPRESSOR structure, and a
         * static reference to the WT_EXTENSION_API methods, then we don't need
         * to allocate memory when the compressor is initialized or free it when
         * the compressor is terminated.  However, this approach is more general
         * purpose and supports multiple databases per application.
         */
        nop_compressor->compressor.compress = nop_compress;
        nop_compressor->compressor.compress_raw = NULL;
        nop_compressor->compressor.decompress = nop_decompress;
        nop_compressor->compressor.pre_size = nop_pre_size;
        nop_compressor->compressor.terminate = nop_terminate;

        nop_compressor->wt_api = connection->get_extension_api(connection);

                                                /* Load the compressor */
        return (connection->add_compressor(
            connection, "nop", (WT_COMPRESSOR *)nop_compressor, NULL));
}

Member Data Documentation

int(* WT_EXTENSION_API::collate)(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_ITEM *first, WT_ITEM *second, int *cmp)

The extension collator method.

Parameters

	wt_api	the extension handle
	session	the session handle (or NULL if none available)
	first	first item
	second	second item
[out]	cmp	set less than 0 if first collates less than second, set equal to 0 if first collates equally to second, set greater than 0 if first collates greater than second

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_ITEM first, second;
        int cmp;

        first.data = key1;
        first.size = key1_len;
        second.data = key2;
        second.size = key2_len;

        ret = wt_api->collate(wt_api, session, &first, &second, &cmp);
        if (cmp == 0)
                printf("key1 collates identically to key2\n");
        else if (cmp < 0)
                printf("key1 collates less than key2\n");
        else
                printf("key1 collates greater than key2\n");

int(* WT_EXTENSION_API::collator_config)(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_CONFIG_ARG *config)

Configure the extension collator method.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
config	the configuration information passed to an application

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        /*
         * Configure the appropriate collator.
         */
        if ((ret = wt_api->collator_config(wt_api, session, config)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "collator configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }

int(* WT_EXTENSION_API::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 string.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
key	configuration key string
config	the configuration information passed to an application
value	the returned value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_CONFIG_ITEM v;
        const char *my_data_source_key;

        /*
         * Retrieve the value of the string type configuration string
         * "key_format".
         */
        if ((ret = wt_api->config_get(
            wt_api, session, config, "key_format", &v)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "key_format configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }

        /*
         * Values returned from WT_EXTENSION_API::config in the str field are
         * not nul-terminated; the associated length must be used instead.
         */
        if (v.len == 1 && v.str[0] == 'r')
                my_data_source_key = "recno";
        else
                my_data_source_key = "bytestring";

int(* WT_EXTENSION_API::config_scan_begin)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *str, size_t len, WT_CONFIG_SCAN **scanp)

Return the list entries of a configuration string value.

This method steps through the entries found in the last returned value from WT_EXTENSION_API::config_get. The last returned value should be of type "list".

Parameters

	wt_api	the extension handle
	session	the session handle (or NULL if none available)
	str	the configuration string to scan
	len	the number of valid bytes in str
[out]	scanp	a handle used to scan the config string

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_CONFIG_ITEM k, v;
        WT_CONFIG_SCAN *scan;

        /*
         * Retrieve the value of the list type configuration string "paths".
         */
        if ((ret = wt_api->config_get(
            wt_api, session, config, "paths", &v)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "paths configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }

        /*
         * Step through the list of entries.
         */
        ret = wt_api->config_scan_begin(wt_api, session, v.str, v.len, &scan);
        while ((ret = wt_api->config_scan_next(wt_api, scan, &k, &v)) == 0)
                printf("%.*s\n", (int)k.len, k.str);
        ret = wt_api->config_scan_end(wt_api, scan);

int(* WT_EXTENSION_API::config_scan_end)(WT_EXTENSION_API *wt_api, WT_CONFIG_SCAN *scan)

Release any resources allocated by WT_EXTENSION_API::config_scan_begin.

Parameters

wt_api	the extension handle
scan	the configuration scanner, invalid after this call

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_CONFIG_ITEM k, v;
        WT_CONFIG_SCAN *scan;

        /*
         * Retrieve the value of the list type configuration string "paths".
         */
        if ((ret = wt_api->config_get(
            wt_api, session, config, "paths", &v)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "paths configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }

        /*
         * Step through the list of entries.
         */
        ret = wt_api->config_scan_begin(wt_api, session, v.str, v.len, &scan);
        while ((ret = wt_api->config_scan_next(wt_api, scan, &k, &v)) == 0)
                printf("%.*s\n", (int)k.len, k.str);
        ret = wt_api->config_scan_end(wt_api, scan);

int(* WT_EXTENSION_API::config_scan_next)(WT_EXTENSION_API *wt_api, WT_CONFIG_SCAN *scan, WT_CONFIG_ITEM *key, WT_CONFIG_ITEM *value)

Return the next key/value pair from a config string scan.

If the string contains a list of items with no assigned value, the items will be returned in key and the value will be set to the boolean "true" value.

Parameters

wt_api	the extension handle
scan	the configuration scanner
key	the returned key
value	the returned value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_CONFIG_ITEM k, v;
        WT_CONFIG_SCAN *scan;

        /*
         * Retrieve the value of the list type configuration string "paths".
         */
        if ((ret = wt_api->config_get(
            wt_api, session, config, "paths", &v)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "paths configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }

        /*
         * Step through the list of entries.
         */
        ret = wt_api->config_scan_begin(wt_api, session, v.str, v.len, &scan);
        while ((ret = wt_api->config_scan_next(wt_api, scan, &k, &v)) == 0)
                printf("%.*s\n", (int)k.len, k.str);
        ret = wt_api->config_scan_end(wt_api, scan);

int(* WT_EXTENSION_API::config_strget)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *config, const char *key, WT_CONFIG_ITEM *value)

Return the value of a configuration string.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
config	a configuration string
key	configuration key string
value	the returned value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_CONFIG_ITEM v;
        int64_t my_data_source_page_size;

        /*
         * Retrieve the value of the integer type configuration string
         * "page_size" from a local string (as opposed to the provided
         * WT_CONFIG_ARG reference).
         */
        const char *config_string = "path=/dev/loop,page_size=1024";

        if ((ret = wt_api->config_strget(
            wt_api, session, config_string, "page_size", &v)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "page_size configuration: %s", wiredtiger_strerror(ret));
                return (ret);
        }
        my_data_source_page_size = v.val;

int(* WT_EXTENSION_API::err_printf)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *fmt,...)

Insert an error message into the WiredTiger error stream.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
fmt	a printf-like format specification

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        (void)wt_api->err_printf(
            wt_api, session, "extension error message: %s", msg);

int(* WT_EXTENSION_API::metadata_insert)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value)

Insert a row into the metadata if it does not already exist.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
key	row key
value	row value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        /*
         * Insert a new WiredTiger metadata record.
         */
        const char *key = "datasource_uri";
        const char *value = "data source uri's record";

        if ((ret = wt_api->metadata_insert(wt_api, session, key, value)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "%s: metadata insert: %s", key, wiredtiger_strerror(ret));
                return (ret);
        }

int(* WT_EXTENSION_API::metadata_remove)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key)

Remove a row from the metadata.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
key	row key

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        /*
         * Remove a WiredTiger metadata record.
         */
        const char *key = "datasource_uri";

        if ((ret = wt_api->metadata_remove(wt_api, session, key)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "%s: metadata remove: %s", key, wiredtiger_strerror(ret));
                return (ret);
        }

int(* WT_EXTENSION_API::metadata_search)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char **valuep)

Return a row from the metadata.

Parameters

	wt_api	the extension handle
	session	the session handle (or NULL if none available)
	key	row key
[out]	valuep	the row value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        /*
         * Insert a new WiredTiger metadata record.
         */
        const char *key = "datasource_uri";
        const char *value;

        if ((ret =
            wt_api->metadata_search(wt_api, session, key, &value)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "%s: metadata search: %s", key, wiredtiger_strerror(ret));
                return (ret);
        }
        printf("metadata: %s has a value of %s\n", key, value);

int(* WT_EXTENSION_API::metadata_update)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const char *key, const char *value)

Update a row in the metadata by either inserting a new record or updating an existing record.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
key	row key
value	row value

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        /*
         * Update a WiredTiger metadata record (insert it if it does not yet
         * exist, update it if it does).
         */
        const char *key = "datasource_uri";
        const char *value = "data source uri's record";

        if ((ret = wt_api->metadata_update(wt_api, session, key, value)) != 0) {
                (void)wt_api->err_printf(wt_api, session,
                    "%s: metadata update: %s", key, wiredtiger_strerror(ret));
                return (ret);
        }

int(* WT_EXTENSION_API::msg_printf)(WT_EXTENSION_API *, WT_SESSION *session, const char *fmt,...)

Insert a message into the WiredTiger message stream.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
fmt	a printf-like format specification

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        (void)wt_api->msg_printf(wt_api, session, "extension message: %s", msg);

void*(* WT_EXTENSION_API::scr_alloc)(WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t bytes)

Allocate short-term use scratch memory.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
bytes	the number of bytes of memory needed

Returns

A valid memory reference on success or NULL on error

        void *buffer;
        if ((buffer = wt_api->scr_alloc(wt_api, session, 512)) == NULL) {
                (void)wt_api->err_printf(wt_api, session,
                    "buffer allocation: %s", wiredtiger_strerror(ENOMEM));
                return (ENOMEM);
        }

void(* WT_EXTENSION_API::scr_free)(WT_EXTENSION_API *, WT_SESSION *session, void *ref)

Free short-term use scratch memory.

Parameters

wt_api	the extension handle
session	the session handle (or NULL if none available)
ref	a memory reference returned by WT_EXTENSION_API::scr_alloc

        wt_api->scr_free(wt_api, session, buffer);

const char*(* WT_EXTENSION_API::strerror)(int err)

Return information about an error as a string; the strerror method is a superset of the ISO C99/POSIX 1003.1-2001 function strerror.

        (void)wt_api->err_printf(wt_api,
            session, "WiredTiger error return: %s", wt_api->strerror(ret));

Parameters

err	a return value from a WiredTiger, C library or POSIX function

Returns

a string representation of the error

int(* WT_EXTENSION_API::struct_pack)(WT_EXTENSION_API *wt_api, WT_SESSION *session, void *buffer, size_t size, const char *format,...)

Pack a structure into a buffer.

See wiredtiger_struct_pack for details.

Parameters

wt_api	the extension handle
session	the session handle
buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see Packing and Unpacking Data

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

int(* WT_EXTENSION_API::struct_size)(WT_EXTENSION_API *wt_api, WT_SESSION *session, size_t *sizep, const char *format,...)

Calculate the size required to pack a structure.

See wiredtiger_struct_size for details.

Parameters

wt_api	the extension handle
session	the session handle
sizep	a location where the number of bytes needed for the matching call to WT_EXTENSION_API::struct_pack is returned
format	the data format, see Packing and Unpacking Data

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

int(* WT_EXTENSION_API::struct_unpack)(WT_EXTENSION_API *wt_api, WT_SESSION *session, const void *buffer, size_t size, const char *format,...)

Unpack a structure from a buffer.

See wiredtiger_struct_unpack for details.

Parameters

wt_api	the extension handle
session	the session handle
buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see Packing and Unpacking Data

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

uint64_t(* WT_EXTENSION_API::transaction_id)(WT_EXTENSION_API *wt_api, WT_SESSION *session)

Return the current transaction ID.

Parameters

wt_api	the extension handle
session	the session handle

Returns

the current transaction ID.

        uint64_t transaction_id;

        transaction_id = wt_api->transaction_id(wt_api, session);

int(* WT_EXTENSION_API::transaction_isolation_level)(WT_EXTENSION_API *wt_api, WT_SESSION *session)

Return the current transaction's isolation level; returns one of WT_TXN_ISO_READ_COMMITTED, WT_TXN_ISO_READ_UNCOMMITTED, or WT_TXN_ISO_SNAPSHOT.

Parameters

wt_api	the extension handle
session	the session handle

Returns

the current transaction's isolation level.

        isolation_level = wt_api->transaction_isolation_level(wt_api, session);
        if (isolation_level == WT_TXN_ISO_SNAPSHOT)
                is_snapshot_isolation = 1;
        else
                is_snapshot_isolation = 0;

int(* WT_EXTENSION_API::transaction_notify)(WT_EXTENSION_API *wt_api, WT_SESSION *session, WT_TXN_NOTIFY *notify)

Request notification of transaction resolution by specifying a function to be called when the session's current transaction is either committed or rolled back.

If the transaction is being committed, but the notification function returns an error, the transaction will be rolled back.

Parameters

wt_api	the extension handle
session	the session handle
notify	a handler for commit or rollback events

Returns

zero on success and a non-zero error code on failure. See Error Returns for details.

        WT_TXN_NOTIFY handler;
        handler.notify = data_source_notify;
        ret = wt_api->transaction_notify(wt_api, session, &handler);

uint64_t(* WT_EXTENSION_API::transaction_oldest)(WT_EXTENSION_API *wt_api)

Return the oldest transaction ID not yet visible to a running transaction.

Parameters

wt_api	the extension handle
session	the session handle

Returns

the oldest transaction ID not yet visible to a running transaction.

        uint64_t transaction_oldest;

        transaction_oldest = wt_api->transaction_oldest(wt_api);

int(* WT_EXTENSION_API::transaction_visible)(WT_EXTENSION_API *wt_api, WT_SESSION *session, uint64_t transaction_id)

Return if the current transaction can see the given transaction ID.

Parameters

wt_api	the extension handle
session	the session handle
transaction_id	the transaction ID

Returns

true (non-zero) if the transaction ID is visible to the current transaction.

        is_visible =
            wt_api->transaction_visible(wt_api, session, transaction_id);