C API ReferenceΒΆ

struct omcache_dist_s
#include <omcache_cdef.h>

Public Members

int omcache_version

OMcache client version.

uint32_t points_per_server

Number of ketama points per server.

uint32_t entries_per_point

Number of ketama entries per point.

omc_ketama_point_hash_func * point_hash_func

Hash function for points.

omc_ketama_key_hash_func * key_hash_func

Hash function for keys.

struct omcache_req_s::omcache_req_header_s
#include <omcache_cdef.h>

Public Members

uint8_t magic

Always PROTOCOL_BINARY_REQ (0x80), set by OMcache

uint8_t opcode

Command type.

uint16_t keylen

Length of key, in network byte order.

uint8_t extlen

Length of structured extra data.

uint8_t datatype

Always PROTOCOL_BINARY_RAW_BYTES (0x00), set by OMcache

uint16_t reserved

Reserved, do not set.

uint32_t bodylen

Request body length, in network byte order, includes extra, key and data

uint32_t opaque

Request identifier, set by OMcache.

uint64_t cas

CAS value for synchronization.

struct omcache_req_s
#include <omcache_cdef.h>

Public Members

int server_index

Opaque integer identifying the server to use when the request type does not use a key (NOOP, VERSION and STATS). -1 when server is selected by key.

struct omcache_req_s::omcache_req_header_s header

Memcache binary protocol header struct.

const void * extra

Extra structured data sent for some request types

const unsigned char * key

Object key.

const unsigned char * data

Object value.

struct omcache_server_info_s
#include <omcache_cdef.h>

Public Members

int omcache_version

OMcache client version.

int server_index

Server index.

char * hostname

Hostname of the server.

int port

Port number of the server.

struct omcache_value_s
#include <omcache_cdef.h>

Public Members

int status

Response status (omcache_ret_t)

const unsigned char * key

Response key (if any)

size_t key_len

Response key length.

const unsigned char * data

Response data (if any)

size_t data_len

Response data length.

uint32_t flags

Flags associated with the object.

uint64_t cas

CAS value for synchronization.

uint64_t delta_value

Value returned in delta operations.

file omcache_cdef.h

Typedefs

typedef enum omcache_ret_e omcache_ret_t
typedef struct omcache_s omcache_t
typedef struct omcache_req_s omcache_req_t
typedef struct omcache_value_s omcache_value_t
typedef uint32_t( omc_ketama_point_hash_func)(const char *hostname, const char *portname, uint32_t point, uint32_t *hashes)

Point hashing function for Ketama.

Return
The number of hash values set.
Parameters
  • hostname -

    Memcache server hostname.

  • portname -

    Memcache server portname (may be a symbolic name from /etc/services).

  • point -

    Ketama point index in the range (0 .. dist->point_per_server - 1)

  • hashes -

    Array of dist->entries_per_point hash_values that the hash function needs to set. The function can also set fewer points.

typedef uint32_t( omc_ketama_key_hash_func)(const unsigned char *key, size_t key_len)

Key hashing function for Ketama.

Return
Hash value of the key.
Parameters
  • key -

    Memcache object key.

  • key_len -

    Memcache object key length.

typedef const struct omcache_dist_s omcache_dist_t
typedef void( omcache_log_callback_func)(void *context, int level, const char *msg)

Log callback function type.

Parameters
  • context -

    Opaque context set in omcache_set_log_callback()

  • level -

    Log message level; levels are defined in <sys/syslog.h>.

  • msg -

    The actual log message.

typedef void( omcache_response_callback_func)(omcache_t *mc, omcache_value_t *result, void *context)

Response callback type.

Parameters

typedef struct omcache_server_info_s omcache_server_info_t

Enums

omcache_ret_e enum

Values:

  • OMCACHE_OK = = 0x00 -

    Success.

  • OMCACHE_NOT_FOUND = = 0x01 -

    Key not found from memcached.

  • OMCACHE_KEY_EXISTS = = 0x02 -

    Conflicting key exists in memcached.

  • OMCACHE_TOO_LARGE_VALUE = = 0x03 -

    Value size exceeds maximum.

  • OMCACHE_NOT_STORED = = 0x05 -

    Append or prepend value not stored.

  • OMCACHE_DELTA_BAD_VALUE = = 0x06 -

    Existing value can not be incremented or decremented

  • OMCACHE_FAIL = = 0x0FFF -

    Command failed in memcached.

  • OMCACHE_AGAIN = = 0x1001 -

    Call would block, try again.

  • OMCACHE_INVALID -

    Invalid parameters.

  • OMCACHE_BUFFERED -

    Data buffered in OMcache.

  • OMCACHE_BUFFER_FULL -

    Buffer full, command dropped.

  • OMCACHE_NO_SERVERS -

    No server available.

  • OMCACHE_SERVER_FAILURE -

    Failure communicating to server.

Functions

omcache_t * omcache_init(void)

Create a new OMcache handle.

Return
A new OMcache handle that can be used with other functions.

int omcache_free(omcache_t * mc)

Free an OMcache handle and its resources.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

const char * omcache_strerror(int rc)

Human readable message for an OMcache error code.

Return
Human readable NUL-terminated string (managed by OMcache).
Parameters
  • rc -

    OMcache return code.

int omcache_set_connect_timeout(omcache_t * mc, uint32_t msec)

Set OMcache handle’s connection timeout.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • msec -

    Maximum milliseconds to wait for a connection.

int omcache_set_reconnect_timeout(omcache_t * mc, uint32_t msec)

Set OMcache handle’s reconnect-after-failure timeout.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • msec -

    Number of milliseconds to wait before attempting to reconnect to a failed node.

int omcache_set_dead_timeout(omcache_t * mc, uint32_t msec)

Set OMcache handle’s io operation timeout.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • msec -

    Number of milliseconds to wait until IO operations finish before declaring the node dead.

int omcache_set_send_buffer_max_size(omcache_t * mc, size_t size)

Set OMcache handle’s maximum buffer size for outgoing messages.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • size -

    Maximum number of bytes to buffer for writes. Note that this is maximum buffer size per server. Default is 10 megabytes.

int omcache_set_recv_buffer_max_size(omcache_t * mc, size_t size)

Set OMcache handle’s maximum buffer size for incoming messages.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • size -

    Maximum number of bytes to buffer for reads. Note that this is maximum buffer size per server. Default is 1056 kilobytes which is enough to handle a response of the maximum default size (1MB) but if memcached is run with a different maximum value length setting this setting should be adjusted as well.

int omcache_set_buffering(omcache_t * mc, uint32_t enabled)

Set OMcache handle’s buffering mode.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • enabled -

    If non-zero, all server operations will be buffered and won’t be flushed to the backend before omcache_io is called.

int omcache_set_servers(omcache_t * mc, const char * servers)

Set the server(s) to use with an OMcache handle. OMcache does not currently implement asynchronous name lookups; to avoid connecting to servers from blocking the server list should only include IP addresses.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • servers -

    Comma-separated list of memcached servers. Any existing servers on OMcache’s server list that do not appear on the new list are dropped. The servers that appear on both the currently used and new lists are kept and connections to them are not reset.

int omcache_set_distribution_method(omcache_t * mc, omcache_dist_t * method)

Set a log callback for the OMcache handle.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • method -

    Distribution method (omcache_dist_t) to use.

void omcache_log_stderr(void * context, int level, const char * msg)

Built-in logging function to log to standard error.

Parameters
  • context -

    Const char * log message prefix.

  • level -

    Log message level.

  • msg -

    The actual log message.

int omcache_set_log_callback(omcache_t * mc, int level, omcache_log_callback_func * func, void * context)

Set a log callback for the OMcache handle.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • level -

    Maximum event level for logging, 0 for everything but debug.

  • func -

    Callback function to call for each generated log message.

  • resp_cb_context -

    Opaque context to pass to the callback function.

int omcache_set_response_callback(omcache_t * mc, omcache_response_callback_func * resp_cb, void * resp_cb_context)

Register a callback function for memcached responses.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

  • resp_cb -

    Callback function to call for all responses to requests.

  • resp_cb_context -

    Opaque context to pass to the callback function.

struct pollfd * omcache_poll_fds(omcache_t * mc, int * nfds, int * poll_timeout)

Populate a struct polld array with required actions.

Return
A struct pollfd array (allocated and managed by OMcache).
Parameters
  • mc -

    OMcache handle.

  • nfds -

    Pointer to an integer signifying the number of file descriptors that were returned.

  • poll_timeout -

    Maximum timeout that should be used in poll.

int omcache_reset_buffers(omcache_t * mc)

Clear all OMcache buffers.

Return
OMCACHE_OK on success.
Parameters
  • mc -

    OMcache handle.

int omcache_io(omcache_t * mc, omcache_req_t * reqs, size_t * req_count, omcache_value_t * values, size_t * value_count, int32_t timeout_msec)

Perform I/O with memcached servers: establish connections, read responses, write requests.

Return
OMCACHE_OK If all responses were received; OMCACHE_AGAIN If there is more data to read.
Parameters
  • mc -

    OMcache handle.

  • reqs -

    Array of requests for which we want responses.

  • req_count -

    Number of requests in reqs array. Will be zeroed once all requests have been handled.

  • values -

    Pointer to an array of omcache_value_t structures to store the responses found. If there aren’t enough value structs to store all requests found the responses will be silently dropped. The memory pointed to by pointers in the omcache_value_t structs will be overwritten on subsequent calls to omcache_io and must not be freed by the caller. Note that all request types may not generate a response, namely a GETQ or GETKQ request for a non-existent key will not cause any response to be sent by the server or stored by OMcache even if omcache_io return status is OMCACHE_OK.

  • value_count -

    Number of response structures in values array. Will be modified to contain the number of stored responses.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely until at least one message has been received.

int omcache_command_status(omcache_t * mc, omcache_req_t * req, int32_t timeout_msec)

Send a request to memcache and read the response status.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer; OMCACHE_BUFFER_FULL if buffer was full and data was not written; OMCACHE_NOT_FOUND OMCACHE_KEY_EXISTS OMCACHE_DELTA_BAD_VALUE
Parameters
  • mc -

    OMcache handle.

  • req -

    An omcache_req_t struct containing at the request header and optionally a key and data.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for the response. Zero means no blocking at all and a negative value blocks indefinitely until at a response is received or an error occurs.

int omcache_command(omcache_t * mc, omcache_req_t * reqs, size_t * req_countp, omcache_value_t * values, size_t * value_count, int32_t timeout_msec)

Send multiple requests to memcache and start reading their responses.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer; OMCACHE_BUFFER_FULL if buffer was full and data was not written.
Parameters
  • mc -

    OMcache handle.

  • reqs -

    Array of requests to send, handled like in omcache_io().

  • req_count -

    reqs length, handled like in omcache_io().

  • values -

    Array to store responses in, handled like in omcache_io().

  • value_count -

    values length, handled like in omcache_io().

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for the response. Zero means no blocking at all and a negative value blocks indefinitely until at a response is received or an error occurs.

int omcache_server_index_for_key(omcache_t * mc, const unsigned char * key, size_t key_len)

Look up the server index of OMcache’s internal server list for the server that is used for actions regarding key. The server index can be used with omcache_server_info(), omcache_noop() and omcache_stat().

Return
Server index.
Parameters
  • mc -

    OMcache handle.

  • key -

    The key for server index lookup.

  • key_len -

    Length of key.

omcache_server_info_t * omcache_server_info(omcache_t * mc, int server_index)

Retrieve information about the server at the given index. All returned information is stored locally in OMcache; this function will not perform any I/O.

Return
omcache_server_info_t structure. NULL if server_index is out of bounds.
Parameters
  • mc -

    OMcache handle.

  • server_index -

    Numeric index of the server from OMcache’s internal server list to look up. Use omcache_server_index_for_key() to get the indexes.

int omcache_server_info_free(omcache_t * mc, omcache_server_info_t * info)

Free omcache_server_info_t returned by omcache_server_info()

Return
OMCACHE_OK on success.
Parameters

int omcache_noop(omcache_t * mc, int server_index, int32_t timeout_msec)

Send a no-op to the given server.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NO_SERVERS if server_index is out of bounds.
Parameters
  • mc -

    OMcache handle.

  • server_index -

    Numeric index of the server from OMcache’s internal server list to look up. Use omcache_server_index_for_key() to get the indexes.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_stat(omcache_t * mc, const char * command, omcache_value_t * values, size_t * value_count, int server_index, int32_t timeout_msec)

Look up statistics for the given server. This function can only be used with a response callback, the callback will be called multiple times for a single stat lookup request.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NO_SERVERS if server_index is out of bounds.
Parameters
  • mc -

    OMcache handle.

  • command -

    Statistics type to look up or NULL for general statistics. Possible commands are backend specific, see memcached’s documentation for the values it supports.

  • values -

    Array of omcache_value_t structures to be will be filled with the results of the stats lookup.

  • value_count -

    Number of omcache_value_t structures in values.

  • server_index -

    Numeric index of the server from OMcache’s internal server list to look up. Use omcache_server_index_for_key() to get the indexes.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_flush_all(omcache_t * mc, time_t expiration, int server_index, int32_t timeout_msec)

Flush (delete) all entries from t

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NO_SERVERS if server_index is out of bounds.
Parameters
  • mc -

    OMcache handle.

  • expiration -

    Delete all entries older than this (0 for everything.)

  • server_index -

    Numeric index of the server from OMcache’s internal server list to look up. Use omcache_server_index_for_key() to get the indexes.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_set(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char * value, size_t value_len, time_t expiration, uint32_t flags, uint64_t cas, int32_t timeout_msec)

Set the given key to the given value.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_KEY_EXISTS cas was set and did not match existing value.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key under which the value will be stored.

  • key_len -

    Length of the key.

  • value -

    New value to store in memcached.

  • value_len -

    Length of the value.

  • expiration -

    Expire the value after this time. Memcache server interprets this as relative to current time if the value is less than 60*60*24*30 (30 days) and as an absolute unix timestamp (seconds since 1970) if it’s higher than that.

  • flags -

    Flags to associate with the stored object.

  • cas -

    CAS value for synchronization, if non-zero and an object with a different value already exists in memcached the request will fail with OMCACHE_KEY_EXISTS.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_add(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char * value, size_t value_len, time_t expiration, uint32_t flags, int32_t timeout_msec)

Add the given key with the given value if it does not yet exist in the backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_KEY_EXISTS the key already exists in the backend.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key under which the value will be stored.

  • key_len -

    Length of the key.

  • value -

    New value to store in memcached.

  • value_len -

    Length of the value.

  • expiration -

    Expire the value after this time. See omcache_set() for details.

  • flags -

    Flags to associate with the stored object.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_replace(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char * value, size_t value_len, time_t expiration, uint32_t flags, int32_t timeout_msec)

Replace the value associated with the given key if the key already exists in the backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NOT_FOUND the key was not set in the backend.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key under which the value will be stored.

  • key_len -

    Length of the key.

  • value -

    New value to store in memcached.

  • value_len -

    Length of the value.

  • expiration -

    Expire the value after this time. See omcache_set() for details.

  • flags -

    Flags to associate with the stored object.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_append(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char * value, size_t value_len, uint64_t cas, int32_t timeout_msec)

Append a string to a value already stored in the backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NOT_STORED the key was not set in the backend. OMCACHE_KEY_EXISTS cas was set and did not match existing value.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key under which the value will be modified.

  • key_len -

    Length of the key.

  • value -

    String to append to the existing value.

  • value_len -

    Length of the value.

  • cas -

    CAS value for synchronization, see omcache_set().

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_prepend(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char * value, size_t value_len, uint64_t cas, int32_t timeout_msec)

Prepend a string to a value already stored in the backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NOT_STORED the key was not set in the backend. OMCACHE_KEY_EXISTS cas was set and did not match existing value.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key under which the value will be modified.

  • key_len -

    Length of the key.

  • value -

    String to prepend to the existing value.

  • value_len -

    Length of the value.

  • cas -

    CAS value for synchronization, see omcache_set().

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_increment(omcache_t * mc, const unsigned char * key, size_t key_len, uint64_t delta, uint64_t initial, time_t expiration, uint64_t * value, int32_t timeout_msec)

Atomically increment a counter for the given key.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_DELTA_BAD_VALUE the existing value in the backend is not a valid number.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to access.

  • key_len -

    Length of the key.

  • delta -

    Increment the counter by this number.

  • initial -

    Value to be set if the counter does not yet exist.

  • expiration -

    Expire the value after this time. If set to OMCACHE_DELTA_NO_ADD the counter is not initialized in case it does not yet exist in the backend. See omcache_set() for details.

  • value -

    Counter value after the increment operation.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_decrement(omcache_t * mc, const unsigned char * key, size_t key_len, uint64_t delta, uint64_t initial, time_t expiration, uint64_t * value, int32_t timeout_msec)

Atomically decrement a counter for the given key.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_DELTA_BAD_VALUE the existing value in the backend is not a valid number.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to access.

  • key_len -

    Length of the key.

  • delta -

    Decrement the counter by this number.

  • initial -

    Value to be set if the counter does not yet exist.

  • expiration -

    Expire the value after this time. If set to OMCACHE_DELTA_NO_ADD the counter is not initialized in case it does not yet exist in the backend. See omcache_set() for details.

  • value -

    Counter value after the decrement operation.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_delete(omcache_t * mc, const unsigned char * key, size_t key_len, int32_t timeout_msec)

Delete a key from the backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NOT_FOUND the key was not set in the backend.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to delete.

  • key_len -

    Length of the key.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_touch(omcache_t * mc, const unsigned char * key, size_t key_len, time_t expiration, int32_t timeout_msec)

‘Touch’ a key in the backend to extend its validity.

Return
OMCACHE_OK if data was successfully written; OMCACHE_BUFFERED if data was successfully added to write buffer. OMCACHE_NOT_FOUND the key was not set in the backend.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to touch.

  • key_len -

    Length of the key.

  • expiration -

    Expire the value after this time. See omcache_set() for details.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_get(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char ** value, size_t * value_len, uint32_t * flags, uint64_t * cas, int32_t timeout_msec)

Look up a key from a backend.

Return
OMCACHE_OK if data was successfully written; OMCACHE_NOT_FOUND the key was not set in the backend. OMCACHE_AGAIN value was not yet retrieved, call omcache_io() to get it later.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to look up.

  • key_len -

    Length of the key.

  • value -

    Pointer to store the new value in, may be NULL.

  • value_len -

    Pointer to store the length of the value in.

  • flags -

    Pointer to store the retrieved object’s flags in.

  • cas -

    Pointer to store the retrieved object’s CAS value in.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_get_multi(omcache_t * mc, const unsigned char ** keys, size_t * key_lens, size_t key_count, omcache_req_t * reqs, size_t * req_count, omcache_value_t * values, size_t * value_count, int32_t timeout_msec)

Look up multiple keys from the backends.

Return
OMCACHE_OK All requests were handled; OMCACHE_AGAIN Not all values were retrieved, call omcache_io() to retrieve them.
Parameters
  • mc -

    OMcache handle.

  • keys -

    Array of pointers to keys to look up.

  • key_lens -

    Array of lengths of keys.

  • key_count -

    Number of pointers in keys array.

  • reqs -

    Array of request structures to store pending requests in. If this function can’t complete all lookups in a single round of I/O operations the pending requests are stored in this array which can be passed to omcache_io() to complete the remaining requests.

  • req_count -

    Number of requests in reqs array. Will be zeroed once all requests have been handled.

  • values -

    Array to store responses in, handled like in omcache_io().

  • value_count -

    values length, handled like in omcache_io().

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_gat(omcache_t * mc, const unsigned char * key, size_t key_len, const unsigned char ** value, size_t * value_len, time_t expiration, uint32_t * flags, uint64_t * cas, int32_t timeout_msec)

Look up a key from a backend and update its expiration time.

Return
OMCACHE_OK if data was successfully written; OMCACHE_NOT_FOUND the key was not set in the backend. OMCACHE_AGAIN value was not yet retrieved, call omcache_io() to get it later.
Parameters
  • mc -

    OMcache handle.

  • key -

    Key to look up.

  • key_len -

    Length of the key.

  • value -

    Pointer to store the new value in, may be NULL.

  • value_len -

    Pointer to store the length of the value in.

  • expiration -

    Expire the key after this time. See omcache_set() for details.

  • flags -

    Pointer to store the retrieved object’s flags in.

  • cas -

    Pointer to store the retrieved object’s CAS value in.

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

int omcache_gat_multi(omcache_t * mc, const unsigned char ** keys, size_t * key_lens, time_t * expirations, size_t key_count, omcache_req_t * requests, size_t * req_count, omcache_value_t * values, size_t * value_count, int32_t timeout_msec)

Look up multiple keys from the backends and update their expiration times.

Return
OMCACHE_OK All requests were handled; OMCACHE_AGAIN Not all values were retrieved, call omcache_io() to retrieve them.
Parameters
  • mc -

    OMcache handle.

  • keys -

    Array of pointers to keys to look up.

  • key_lens -

    Array of lengths of keys.

  • expirations -

    Array of new expiration times for the keys. See omcache_set() for details.

  • key_count -

    Number of pointers in keys array.

  • reqs -

    Array of request structures to store pending requests in. If this function can’t complete all lookups in a single round of I/O operations the pending requests are stored in this array which can be passed to omcache_io() to complete the remaining requests.

  • req_count -

    Number of requests in reqs array. Will be zeroed once all requests have been handled.

  • values -

    Array to store responses in, handled like in omcache_io().

  • value_count -

    values length, handled like in omcache_io().

  • timeout_msec -

    Maximum number of milliseconds to block while waiting for I/O to complete. Zero means no blocking at all and a negative value blocks indefinitely.

Variables

omcache_dist_t omcache_dist_libmemcached_ketama

Consistent distribution function compatible with libmemcached’s MEMCACHED_BEHAVIOR_KETAMA

NOTE: use omcache_dist_libmemcached_ketama_pre110 for compatibility with libmemcached versions before 1.0.10 as those versions had a bug that caused distribution to use md5 for hosts and Jenkins hash for keys.

This is the default distribution method.

omcache_dist_t omcache_dist_libmemcached_ketama_weighted

Consistent distribution function compatible with libmemcached’s MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED when all server weights are 1. OMcache does not have a concept of server weights at the moment.

omcache_dist_t omcache_dist_libmemcached_ketama_pre1010

Consistent distribution function compatible with libmemcached’s MEMCACHED_BEHAVIOR_KETAMA prior to libmemcached 1.0.10

NOTE: libmemcached prior to 1.0.10 always used MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED even if MEMCACHED_BEHAVIOR_KETAMA was requested, but kept using Jenkins one-at-a-time hash for keys making it incompatible with correctly any operating distribution method, see https://bugs.launchpad.net/libmemcached/+bug/1009493