Detailed Description

Additional functions for scheduling operations

An application may spool multiple operations into the library with the option of unspooling previously-spooled operations in case one of the operations cannot be spooled. These semantics exist primarily to support "all-or-nothing" scheduling found in the V2 API as well as in some other wrapping SDKs.

From version 2.4.0 to version 2.5.5, use of the explicit scheduling API was mandatory to schedule operations. This API is optional since 2.5.6.

The following operation APIs are low level entry points which create a single operation. To use these operation APIs you should call the lcb_sched_enter() which creates a virtual scope in which to create operations.

For each of these operation APIs, the actual API call will insert the created packet into a "Scheduling Queue" (this is done through mcreq_sched_add() which is in mcreq.h). You may add as many items to this scheduling queue as you would like.

Note that an operation is only added to the queue if it was able to be scheduled properly. If a scheduling failure occurred (for example, if a configuration is missing, the command had invalid input, or memory allocation failed) then the command will not be placed into the queue.

Once all operations have been scheduled you can call lcb_sched_leave() which will place all commands scheduled into the I/O queue.

If you wish to discard all scheduled operations (for example, if one of them errored, and your application cannot handle partial scheduling failures) then you may call lcb_sched_fail() which will release all the resources of the packets placed into the temporary queue.

Behavior from version 2.5.6

Starting from version 2.5.6, use of this API is optional. Scheduling functions will now check if an empty call to lcb_sched_enter() is present. If no call to lcb_sched_enter() is found then the library will implicitly call lcb_sched_leave().

Function Documentation

◆ lcb_sched_enter()

void lcb_sched_enter ( lcb_INSTANCE * instance )

Enter a scheduling context.

Stability

Uncommitted

A scheduling context is an ephemeral list of commands issued to various servers. Operations (like lcb_get3(), lcb_store3()) place packets into the current context.

The context mechanism allows you to efficiently pipeline and schedule multiple operations of different types and quantities. The network is not touched and nothing is scheduled until the context is exited.

Parameters

instance the instance

lcb_sched_enter(instance);
lcb_get(...);
lcb_store(...);
lcb_counter(...);
lcb_sched_leave(instance);
lcb_wait(instance, LCB_WAIT_NOCHECK);

Examples: example/subdoc/subdoc-xattrs.c.

◆ lcb_sched_leave()

void lcb_sched_leave ( lcb_INSTANCE * instance )

Leave the current scheduling context, scheduling the commands within the context to be flushed to the network.

Stability

Uncommitted

This will initiate a network-level flush (depending on the I/O system) to the network. For completion-based I/O systems this typically means allocating a temporary write context to contain the buffer. If using a completion-based I/O module (for example, Windows or libuv) then it is recommended to limit the number of calls to one per loop iteration. If limiting the number of calls to this function is not possible (for example, if the legacy API is being used, or you wish to use implicit scheduling) then the flushing may be decoupled from this function - see the documentation for lcb_sched_flush().

Parameters

instance the instance

Examples: example/subdoc/subdoc-xattrs.c.

◆ lcb_sched_fail()

void lcb_sched_fail ( lcb_INSTANCE * instance )

Fail all commands in the current scheduling context.

Stability

Uncommitted

The commands placed within the current scheduling context are released and are never flushed to the network.

Parameters

instance

Warning: This function only affects commands which have a direct correspondence to memcached packets. Currently these are commands scheduled by:

lcb_get()
lcb_getreplica()
lcb_unlock()
lcb_touch()
lcb_store()
lcb_counter()
lcb_remove()

Other commands are compound commands and thus should be in their own scheduling context.

◆ lcb_sched_flush()

void lcb_sched_flush ( lcb_INSTANCE * instance )

Request commands to be flushed to the network.

Stability

Committed

By default, the library will implicitly request a flush to the network upon every call to lcb_sched_leave().

[ Note, this does not mean the items are flushed and I/O is performed, but it means the relevant event loop watchers are activated to perform the operations on the next iteration ]. If LCB_CNTL_SCHED_IMPLICIT_FLUSH is disabled then this behavior is disabled and the application must explicitly call lcb_sched_flush(). This may be considered more performant in the cases where multiple discreet operations are scheduled in an lcb_sched_enter()/lcb_sched_leave() pair. With implicit flush enabled, each call to lcb_sched_leave() will possibly invoke system repeatedly.