A WT_ASYNC_OP handle is the interface to an asynchronous operation. More...

Public Member Functions
int	search (WT_ASYNC_OP *op)
	Return the record matching the key. More...

Data access
int	get_key (WT_ASYNC_OP *op,...)
	Get the key for the current record. More...

int	get_value (WT_ASYNC_OP *op,...)
	Get the value for the current record. More...

void	set_key (WT_ASYNC_OP *op,...)
	Set the key for the next operation. More...

void	set_value (WT_ASYNC_OP *op,...)
	Set the value for the next operation. More...

Data modification
int	insert (WT_ASYNC_OP *op)
	Insert a record and optionally update an existing record. More...

int	update (WT_ASYNC_OP *op)
	Update a record and optionally insert an existing record. More...

int	remove (WT_ASYNC_OP *op)
	Remove a record. More...

int	compact (WT_ASYNC_OP *op)
	Compact a live row- or column-store btree or LSM tree. More...

uint64_t	get_id (WT_ASYNC_OP *op)
	Get the unique identifier for this operation. More...

WT_ASYNC_OPTYPE	get_type (WT_ASYNC_OP *op)
	Get the type for this operation. More...

Public Attributes
WT_CONNECTION *	connection
	The connection for this operation. More...

const char *	key_format
	The format of the data packed into key items. More...

const char *	value_format
	The format of the data packed into value items. More...

void *	app_private
	A location for applications to store information that will be available in the callback from an async operation.

Detailed Description

A WT_ASYNC_OP handle is the interface to an asynchronous operation.

An asynchronous operation describes a data manipulation to be performed asynchronously by a WiredTiger worker thread. These operations implement the CRUD (create, read, update and delete) operations. Each operation is a self-contained work unit. The operation will be performed in the context of the worker thread's session. Each operation is performed within the context of a transaction. The application is notified of its completion with a callback. The transaction is resolved once the callback returns.

The table referenced in an operation must already exist.

Raw data is represented by key/value pairs of WT_ITEM structures, but operations can also provide access to fields within the key and value if the formats are described in the WT_SESSION::create method.

Thread safety: A WT_ASYNC_OP handle is not shared between threads.

Member Function Documentation

int WT_ASYNC_OP::compact ( WT_ASYNC_OP * op )

Compact a live row- or column-store btree or LSM tree.

        ret = wt_conn->async_new_op(wt_conn, uri, "timeout=10",
            &ex_asynckeys.iface, &op);
        op->compact(op);

Parameters

op	the operation handle

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

uint64_t WT_ASYNC_OP::get_id ( WT_ASYNC_OP * op )

Get the unique identifier for this operation.

id = op->get_id(op);

Parameters

op	the operation handle

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

int WT_ASYNC_OP::get_key	(	WT_ASYNC_OP *	op,
			...
	)

Get the key for the current record.

t_ret = op->get_key(op, &k);

key = k.data;

Parameters

op	the operation handle
...	pointers to hold key fields corresponding to WT_ASYNC_OP::key_format.

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

WT_ASYNC_OPTYPE WT_ASYNC_OP::get_type ( WT_ASYNC_OP * op )

Get the type for this operation.

type = op->get_type(op);

Parameters

op	the operation handle

Returns: the WT_ASYNC_OPTYPE of this operation; zero on success and a non-zero error code on failure. See Error Returns for details.

int WT_ASYNC_OP::get_value	(	WT_ASYNC_OP *	op,
			...
	)

Get the value for the current record.

                t_ret = op->get_value(op, &v);
                value = v.data;
                ATOMIC_ADD(asynckey->num_keys, 1);

Parameters

op	the operation handle
...	pointers to hold value fields corresponding to WT_ASYNC_OP::value_format.

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

int WT_ASYNC_OP::insert ( WT_ASYNC_OP * op )

Insert a record and optionally update an existing record.

If the operation was configured with "overwrite=true" (the default), both the key and value must be set; if the record already exists, the key's value will be updated, otherwise, the record will be inserted.

        /* Insert a new record or overwrite an existing record. */
        const char *key = "some key", *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);

If the operation was not configured with "overwrite=true", both the key and value must be set and the record must not already exist; the record will be inserted.

        /* Insert a new record and fail if the record exists. */
        const char *key = "some key", *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "overwrite=false", &cursor);
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);

If an operation with record number keys was configured with "append=true" (not the default), the value must be set; a new record will be appended and the record number set as the operation's key value.

        /* Insert a new record and assign a record number. */
        uint64_t recno;
        const char *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "append", &cursor);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);
        if (ret == 0)
                ret = cursor->get_key(cursor, &recno);

Inserting a new record after the current maximum record in a fixed-length bit field column-store (that is, a store with an 'r' type key and 't' type value) may implicitly create the missing records as records with a value of 0.

When loading a large amount of data into a new object, using normal cursor operations with the bulk configuration string enabled will be much faster than asynchronous operations.

The maximum length of a single column stored in a table is not fixed (as it partially depends on the underlying file configuration), but is always a small number of bytes less than 4GB.

Parameters

op	the operation handle

Returns: zero on success and a non-zero error code on failure. See Error Returns for details. In particular, if overwrite is not configured and a record with the specified key already exists, WT_DUPLICATE_KEY is returned.

int WT_ASYNC_OP::remove ( WT_ASYNC_OP * op )

Remove a record.

If the operation was configured with "overwrite=true" (the default), the key must be set; the key's record will be removed if it exists, no error will be returned if the record does not exist.

        const char *key = "some key";
        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
        cursor->set_key(cursor, key);
        ret = cursor->remove(cursor);

If the operation was not configured with "overwrite=true", the key must be set and the key's record must exist; the record will be removed.

        const char *key = "some key";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "overwrite=false", &cursor);
        cursor->set_key(cursor, key);
        ret = cursor->remove(cursor);

Removing a record in a fixed-length bit field column-store (that is, a store with an 'r' type key and 't' type value) is identical to setting the record's value to 0.

Parameters

op	the operation handle

Returns: zero on success and a non-zero error code on failure. See Error Returns for details. In particular, if overwrite is not configured and no record with the specified key exists, WT_NOTFOUND is returned.

int WT_ASYNC_OP::search ( WT_ASYNC_OP * op )

Return the record matching the key.

The key must first be set.

op->search(op);

On success, the operation contains the returned record.

Parameters

op	the operation handle

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

void WT_ASYNC_OP::set_key	(	WT_ASYNC_OP *	op,
			...
	)

Set the key for the next operation.

op->set_key(op, k[i]);

Parameters

op	the operation handle
...	key fields corresponding to WT_ASYNC_OP::key_format.

If an error occurs during this operation, a flag will be set in the operation, and the next operation to access the key will fail. This simplifies error handling in applications.

void WT_ASYNC_OP::set_value	(	WT_ASYNC_OP *	op,
			...
	)

Set the value for the next operation.

op->set_value(op, v[i]);

Parameters

op	the operation handle
...	value fields corresponding to WT_ASYNC_OP::value_format.

If an error occurs during this operation, a flag will be set in the operation, and the next operation to access the value will fail This simplifies error handling in applications.

int WT_ASYNC_OP::update ( WT_ASYNC_OP * op )

Update a record and optionally insert an existing record.

If the operation was configured with "overwrite=true" (the default), both the key and value must be set; if the record already exists, the key's value will be updated, otherwise, the record will be inserted.

        const char *key = "some key", *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->update(cursor);

If the operation was not configured with "overwrite=true", both the key and value must be set and the record must already exist; the record will be updated.

        const char *key = "some key", *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "overwrite=false", &cursor);
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->update(cursor);

The maximum length of a single column stored in a table is not fixed (as it partially depends on the underlying file configuration), but is always a small number of bytes less than 4GB.

Parameters

op	the operation handle

Returns: zero on success and a non-zero error code on failure. See Error Returns for details. In particular, if overwrite is not configured and no record with the specified key exists, WT_NOTFOUND is returned.

Member Data Documentation

WT_CONNECTION* WT_ASYNC_OP::connection

The connection for this operation.

const char* WT_ASYNC_OP::key_format

The format of the data packed into key items.

See Packing and Unpacking Data for details. If not set, a default value of "u" is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

const char* WT_ASYNC_OP::value_format

The format of the data packed into value items.

See Packing and Unpacking Data for details. If not set, a default value of "u" is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation