156fef3acSTrond Norbye/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
22466734eSTrond Norbye#ifndef MEMCACHED_ENGINE_H
32466734eSTrond Norbye#define MEMCACHED_ENGINE_H
42466734eSTrond Norbye
5bbafc072STrond Norbye#ifndef __cplusplus
62466734eSTrond Norbye#include <stdbool.h>
7bbafc072STrond Norbye#endif
8bbafc072STrond Norbye
9bbafc072STrond Norbye#include <sys/types.h>
102466734eSTrond Norbye#include <stdint.h>
1191eb4700STrond Norbye#include <stdio.h>
122466734eSTrond Norbye
138f89d2eaSDustin Sallings#include "memcached/types.h"
142466734eSTrond Norbye#include "memcached/protocol_binary.h"
1591eb4700STrond Norbye#include "memcached/config_parser.h"
16334cfbbfSTrond Norbye#include "memcached/server_api.h"
17886999e2STrond Norbye#include "memcached/callback.h"
18e1175713SMike Wiederhold#include "memcached/allocator_hooks.h"
198f89d2eaSDustin Sallings#include "memcached/extension.h"
20e6449479STrond Norbye#include "memcached/vbucket.h"
21fc06711bSDustin Sallings#include "memcached/engine_common.h"
22f1818198STrond Norbye#include "memcached/dcp.h"
232466734eSTrond Norbye
242466734eSTrond Norbye#ifdef __cplusplus
252466734eSTrond Norbyeextern "C" {
262466734eSTrond Norbye#endif
272466734eSTrond Norbye
2802ae1f50SDustin Sallings/*! \mainpage memcached public API
2902ae1f50SDustin Sallings *
3002ae1f50SDustin Sallings * \section intro_sec Introduction
3102ae1f50SDustin Sallings *
3202ae1f50SDustin Sallings * The memcached project provides an API for providing engines as well
3302ae1f50SDustin Sallings * as data definitions for those implementing the protocol in C.  This
3402ae1f50SDustin Sallings * documentation will explain both to you.
3502ae1f50SDustin Sallings *
3602ae1f50SDustin Sallings * \section docs_sec API Documentation
3702ae1f50SDustin Sallings *
3802ae1f50SDustin Sallings * Jump right into <a href="modules.html">the modules docs</a> to get started.
3902ae1f50SDustin Sallings *
4002ae1f50SDustin Sallings * \example default_engine.c
4102ae1f50SDustin Sallings */
4202ae1f50SDustin Sallings
4302ae1f50SDustin Sallings/**
4402ae1f50SDustin Sallings * \defgroup Engine Storage Engine API
4502ae1f50SDustin Sallings * \defgroup Protex Protocol Extension API
4602ae1f50SDustin Sallings * \defgroup Protocol Binary Protocol Structures
4702ae1f50SDustin Sallings *
4802ae1f50SDustin Sallings * \addtogroup Engine
4902ae1f50SDustin Sallings * @{
5002ae1f50SDustin Sallings *
5102ae1f50SDustin Sallings * Most interesting here is to implement engine_interface_v1 for your
5202ae1f50SDustin Sallings * engine.
5302ae1f50SDustin Sallings */
5402ae1f50SDustin Sallings
552466734eSTrond Norbye#define ENGINE_INTERFACE_VERSION 1
562466734eSTrond Norbye
57c7b0a5fbSDustin Sallings
58c7b0a5fbSDustin Sallings    /**
59c7b0a5fbSDustin Sallings     * Abstract interface to an engine.
60c7b0a5fbSDustin Sallings     */
61f603fdb6STrond Norbye#ifdef WIN32
6295c3be87SPatrick Galbraith#undef interface
6395c3be87SPatrick Galbraith#endif
6484d6c30cSTrond Norbye    struct item_observer_cb_data {
6584d6c30cSTrond Norbye        const void *key; /* THis isn't going to work from a memory management perspective */
6684d6c30cSTrond Norbye        size_t nkey;
6784d6c30cSTrond Norbye    };
6884d6c30cSTrond Norbye
698f89d2eaSDustin Sallings    /* This is typedefed in types.h */
708f89d2eaSDustin Sallings    struct server_handle_v1_t {
718f89d2eaSDustin Sallings        uint64_t interface; /**< The version number on the server structure */
728f89d2eaSDustin Sallings        SERVER_CORE_API *core;
738f89d2eaSDustin Sallings        SERVER_STAT_API *stat;
748f89d2eaSDustin Sallings        SERVER_EXTENSION_API *extension;
758f89d2eaSDustin Sallings        SERVER_CALLBACK_API *callback;
76195aa8f9STrond Norbye        ENGINE_HANDLE *engine;
77019c4a2cSTrond Norbye        SERVER_LOG_API *log;
786c5ff8d7STrond Norbye        SERVER_COOKIE_API *cookie;
79e1175713SMike Wiederhold        ALLOCATOR_HOOKS_API *alloc_hooks;
808f89d2eaSDustin Sallings    };
818f89d2eaSDustin Sallings
8284d6c30cSTrond Norbye    typedef enum { TAP_MUTATION = 1,
8384d6c30cSTrond Norbye                   TAP_DELETION,
8484d6c30cSTrond Norbye                   TAP_FLUSH,
8584d6c30cSTrond Norbye                   TAP_OPAQUE,
86e6449479STrond Norbye                   TAP_VBUCKET_SET,
8784d6c30cSTrond Norbye                   TAP_ACK,
881b0c371bSTrond Norbye                   TAP_DISCONNECT,
8908118093STrond Norbye                   TAP_NOOP,
908714ec42SChiyoung Seo                   TAP_PAUSE,
918714ec42SChiyoung Seo                   TAP_CHECKPOINT_START,
928714ec42SChiyoung Seo                   TAP_CHECKPOINT_END } tap_event_t;
9384d6c30cSTrond Norbye
9484d6c30cSTrond Norbye    /**
9584d6c30cSTrond Norbye     * An iterator for the tap stream.
9684d6c30cSTrond Norbye     * The memcached core will keep on calling this function as long as a tap
9784d6c30cSTrond Norbye     * client is connected to the server. Each event returned by the iterator
9884d6c30cSTrond Norbye     * will be encoded in the binary protocol with the appropriate command opcode.
9984d6c30cSTrond Norbye     *
10084d6c30cSTrond Norbye     * If the engine needs to store extra information in the tap stream it should
10184d6c30cSTrond Norbye     * do so by returning the data through the engine_specific pointer. This data
10284d6c30cSTrond Norbye     * should be valid for the core to use (read only) until the next invocation
10384d6c30cSTrond Norbye     * of the iterator, of if the connection is closed.
10484d6c30cSTrond Norbye     *
10584d6c30cSTrond Norbye     * @param handle the engine handle
10684d6c30cSTrond Norbye     * @param cookie identification for the tap stream
10784d6c30cSTrond Norbye     * @param item item to send returned here (check tap_event_t)
10884d6c30cSTrond Norbye     * @param engine_specific engine specific data returned here
10984d6c30cSTrond Norbye     * @param nengine_specific number of bytes of engine specific data
11084d6c30cSTrond Norbye     * @param ttl ttl for this item (Tap stream hops)
11184d6c30cSTrond Norbye     * @param flags tap flags for this object
11284d6c30cSTrond Norbye     * @param seqno sequence number to send
113eeaeeedeSTrond Norbye     * @param vbucket the virtual bucket id
11484d6c30cSTrond Norbye     * @return the tap event to send (or TAP_PAUSE if there isn't any events)
11584d6c30cSTrond Norbye     */
11684d6c30cSTrond Norbye    typedef tap_event_t (*TAP_ITERATOR)(ENGINE_HANDLE* handle,
11784d6c30cSTrond Norbye                                        const void *cookie,
11884d6c30cSTrond Norbye                                        item **item,
11984d6c30cSTrond Norbye                                        void **engine_specific,
12084d6c30cSTrond Norbye                                        uint16_t *nengine_specific,
12184d6c30cSTrond Norbye                                        uint8_t *ttl,
12284d6c30cSTrond Norbye                                        uint16_t *flags,
123eeaeeedeSTrond Norbye                                        uint32_t *seqno,
124eeaeeedeSTrond Norbye                                        uint16_t *vbucket);
12584d6c30cSTrond Norbye
126288d1a8bSTrond Norbye    typedef ENGINE_ERROR_CODE (*engine_get_vb_map_cb)(const void *cookie,
127288d1a8bSTrond Norbye                                                      const void *map,
128288d1a8bSTrond Norbye                                                      size_t mapsize);
129288d1a8bSTrond Norbye
13014785bd3SDustin Sallings    /**
13114785bd3SDustin Sallings     * The signature for the "create_instance" function exported from the module.
13214785bd3SDustin Sallings     *
13314785bd3SDustin Sallings     * This function should fill out an engine inteface structure according to
13414785bd3SDustin Sallings     * the interface parameter (Note: it is possible to return a lower version
13514785bd3SDustin Sallings     * number).
13614785bd3SDustin Sallings     *
13714785bd3SDustin Sallings     * @param interface The highest interface level the server supports
13856fef3acSTrond Norbye     * @param get_server_api function to get the server API from
13914785bd3SDustin Sallings     * @param Where to store the interface handle
14014785bd3SDustin Sallings     * @return See description of ENGINE_ERROR_CODE
14114785bd3SDustin Sallings     */
14214785bd3SDustin Sallings    typedef ENGINE_ERROR_CODE (*CREATE_INSTANCE)(uint64_t interface,
14356fef3acSTrond Norbye                                                 GET_SERVER_API get_server_api,
14414785bd3SDustin Sallings                                                 ENGINE_HANDLE** handle);
14514785bd3SDustin Sallings
146d6a62e9bSTrond Norbye    typedef enum {
147d6a62e9bSTrond Norbye        ENGINE_FEATURE_CAS, /**< has compare-and-set operation */
148d6a62e9bSTrond Norbye        ENGINE_FEATURE_PERSISTENT_STORAGE, /**< has persistent storage support*/
149d6a62e9bSTrond Norbye        ENGINE_FEATURE_SECONDARY_ENGINE, /**< performs as pseudo engine */
150d6a62e9bSTrond Norbye        ENGINE_FEATURE_ACCESS_CONTROL, /**< has access control feature */
151d6a62e9bSTrond Norbye        ENGINE_FEATURE_MULTI_TENANCY,
152eeaeeedeSTrond Norbye        ENGINE_FEATURE_LRU, /* Cache implements an LRU */
15359f16914STrond Norbye        ENGINE_FEATURE_VBUCKET, /* Cache implements virtual buckets */
15459f16914STrond Norbye        ENGINE_FEATURE_DATATYPE /**< uses datatype field */
155eeaeeedeSTrond Norbye
157d6a62e9bSTrond Norbye    } engine_feature_t;
158d6a62e9bSTrond Norbye
159a7235219STrond Norbye    typedef struct {
160a7235219STrond Norbye        /**
161a7235219STrond Norbye         * The identifier of this feature. All values with the most significant bit cleared is reserved
162a7235219STrond Norbye         * for "registered" features.
163a7235219STrond Norbye         */
164a7235219STrond Norbye        uint32_t feature;
165a7235219STrond Norbye        /**
166a7235219STrond Norbye         * A textual description of the feature. (null will print the registered name for the feature
167a7235219STrond Norbye         * (or "Unknown feature"))
168a7235219STrond Norbye         */
169a7235219STrond Norbye        const char *description;
170a7235219STrond Norbye    } feature_info;
171a7235219STrond Norbye
172a7235219STrond Norbye    typedef struct {
173a7235219STrond Norbye        /**
174a7235219STrond Norbye         * Textual description of this engine
175a7235219STrond Norbye         */
176a7235219STrond Norbye        const char *description;
177a7235219STrond Norbye        /**
178a7235219STrond Norbye         * The number of features the server provides
179a7235219STrond Norbye         */
180a7235219STrond Norbye        uint32_t num_features;
181a7235219STrond Norbye        /**
182a7235219STrond Norbye         * An array containing all of the features the engine supports
183a7235219STrond Norbye         */
184a7235219STrond Norbye        feature_info features[1];
185a7235219STrond Norbye    } engine_info;
18614785bd3SDustin Sallings
18714785bd3SDustin Sallings    /**
18814785bd3SDustin Sallings     * Definition of the first version of the engine interface
18914785bd3SDustin Sallings     */
19014785bd3SDustin Sallings    typedef struct engine_interface_v1 {
1918ddc1418SDustin Sallings        /**
1928ddc1418SDustin Sallings         * Engine info.
1938ddc1418SDustin Sallings         */
19414785bd3SDustin Sallings        struct engine_interface interface;
1958ddc1418SDustin Sallings
1968ddc1418SDustin Sallings        /**
1978ddc1418SDustin Sallings         * Get a description of this engine.
1988ddc1418SDustin Sallings         *
1998ddc1418SDustin Sallings         * @param handle the engine handle
2008ddc1418SDustin Sallings         * @return a stringz description of this engine
2018ddc1418SDustin Sallings         */
202a7235219STrond Norbye        const engine_info* (*get_info)(ENGINE_HANDLE* handle);
2038ddc1418SDustin Sallings
2048ddc1418SDustin Sallings        /**
2058ddc1418SDustin Sallings         * Initialize an engine instance.
2068ddc1418SDustin Sallings         * This is called *after* creation, but before the engine may be used.
2078ddc1418SDustin Sallings         *
2088ddc1418SDustin Sallings         * @param handle the engine handle
2098ddc1418SDustin Sallings         * @param config_str configuration this engine needs to initialize itself.
2108ddc1418SDustin Sallings         */
21114785bd3SDustin Sallings        ENGINE_ERROR_CODE (*initialize)(ENGINE_HANDLE* handle,
21214785bd3SDustin Sallings                                        const char* config_str);
2138ddc1418SDustin Sallings
2148ddc1418SDustin Sallings        /**
2158ddc1418SDustin Sallings         * Tear down this engine.
2168ddc1418SDustin Sallings         *
2178ddc1418SDustin Sallings         * @param handle the engine handle
21874ddc806SChiyoung Seo         * @param force the flag indicating the force shutdown or not.
2198ddc1418SDustin Sallings         */
22074ddc806SChiyoung Seo        void (*destroy)(ENGINE_HANDLE* handle, const bool force);
22114785bd3SDustin Sallings
22214785bd3SDustin Sallings        /*
2238ddc1418SDustin Sallings         * Item operations.
2248ddc1418SDustin Sallings         */
2258ddc1418SDustin Sallings
2268ddc1418SDustin Sallings        /**
2278ddc1418SDustin Sallings         * Allocate an item.
2288ddc1418SDustin Sallings         *
2298ddc1418SDustin Sallings         * @param handle the engine handle
2308ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
2318ddc1418SDustin Sallings         * @param output variable that will receive the item
2328ddc1418SDustin Sallings         * @param key the item's key
2338ddc1418SDustin Sallings         * @param nkey the length of the key
2348ddc1418SDustin Sallings         * @param nbytes the number of bytes that will make up the
2358ddc1418SDustin Sallings         *        value of this item.
2368ddc1418SDustin Sallings         * @param flags the item's flags
2378ddc1418SDustin Sallings         * @param exptime the maximum lifetime of this item
2388ddc1418SDustin Sallings         *
2398ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
24014785bd3SDustin Sallings         */
24114785bd3SDustin Sallings        ENGINE_ERROR_CODE (*allocate)(ENGINE_HANDLE* handle,
2422466734eSTrond Norbye                                      const void* cookie,
24314785bd3SDustin Sallings                                      item **item,
2442466734eSTrond Norbye                                      const void* key,
24514785bd3SDustin Sallings                                      const size_t nkey,
24614785bd3SDustin Sallings                                      const size_t nbytes,
24714785bd3SDustin Sallings                                      const int flags,
2481639b21aSabhinavdangeti                                      const rel_time_t exptime,
2491639b21aSabhinavdangeti                                      uint8_t datatype);
2508ddc1418SDustin Sallings
2518ddc1418SDustin Sallings        /**
2528ddc1418SDustin Sallings         * Remove an item.
2538ddc1418SDustin Sallings         *
2548ddc1418SDustin Sallings         * @param handle the engine handle
2558ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
2560c02e805STrond Norbye         * @param key the key identifying the item to be removed
2570c02e805STrond Norbye         * @param nkey the length of the key
258eeaeeedeSTrond Norbye         * @param vbucket the virtual bucket id
2598ddc1418SDustin Sallings         *
2608ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
2618ddc1418SDustin Sallings         */
26214785bd3SDustin Sallings        ENGINE_ERROR_CODE (*remove)(ENGINE_HANDLE* handle,
26314785bd3SDustin Sallings                                    const void* cookie,
2640c02e805STrond Norbye                                    const void* key,
2650c02e805STrond Norbye                                    const size_t nkey,
26685873118SMike Wiederhold                                    uint64_t* cas,
267eeaeeedeSTrond Norbye                                    uint16_t vbucket);
2688ddc1418SDustin Sallings
2698ddc1418SDustin Sallings        /**
2708ddc1418SDustin Sallings         * Indicate that a caller who received an item no longer needs
2718ddc1418SDustin Sallings         * it.
2728ddc1418SDustin Sallings         *
2738ddc1418SDustin Sallings         * @param handle the engine handle
2746c869215SDustin Sallings         * @param cookie The cookie provided by the frontend
2758ddc1418SDustin Sallings         * @param item the item to be released
2768ddc1418SDustin Sallings         */
2776c869215SDustin Sallings        void (*release)(ENGINE_HANDLE* handle, const
2786c869215SDustin Sallings                        void *cookie,
2796c869215SDustin Sallings                        item* item);
2808ddc1418SDustin Sallings
2818ddc1418SDustin Sallings        /**
2828ddc1418SDustin Sallings         * Retrieve an item.
2838ddc1418SDustin Sallings         *
2848ddc1418SDustin Sallings         * @param handle the engine handle
2858ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
2868ddc1418SDustin Sallings         * @param item output variable that will receive the located item
2878ddc1418SDustin Sallings         * @param key the key to look up
2888ddc1418SDustin Sallings         * @param nkey the length of the key
289eeaeeedeSTrond Norbye         * @param vbucket the virtual bucket id
2908ddc1418SDustin Sallings         *
2918ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
2928ddc1418SDustin Sallings         */
29314785bd3SDustin Sallings        ENGINE_ERROR_CODE (*get)(ENGINE_HANDLE* handle,
29414785bd3SDustin Sallings                                 const void* cookie,
29514785bd3SDustin Sallings                                 item** item,
29614785bd3SDustin Sallings                                 const void* key,
297eeaeeedeSTrond Norbye                                 const int nkey,
298eeaeeedeSTrond Norbye                                 uint16_t vbucket);
2998ddc1418SDustin Sallings
3008ddc1418SDustin Sallings        /**
3018ddc1418SDustin Sallings         * Store an item.
3028ddc1418SDustin Sallings         *
3038ddc1418SDustin Sallings         * @param handle the engine handle
3048ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
3058ddc1418SDustin Sallings         * @param item the item to store
3068ddc1418SDustin Sallings         * @param cas the CAS value for conditional sets
3078ddc1418SDustin Sallings         * @param operation the type of store operation to perform.
308eeaeeedeSTrond Norbye         * @param vbucket the virtual bucket id
3098ddc1418SDustin Sallings         *
3108ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
3118ddc1418SDustin Sallings         */
31214785bd3SDustin Sallings        ENGINE_ERROR_CODE (*store)(ENGINE_HANDLE* handle,
31314785bd3SDustin Sallings                                   const void *cookie,
31414785bd3SDustin Sallings                                   item* item,
31514785bd3SDustin Sallings                                   uint64_t *cas,
316eeaeeedeSTrond Norbye                                   ENGINE_STORE_OPERATION operation,
317eeaeeedeSTrond Norbye                                   uint16_t vbucket);
3188ddc1418SDustin Sallings
3198ddc1418SDustin Sallings        /**
3208ddc1418SDustin Sallings         * Perform an increment or decrement operation on an item.
3218ddc1418SDustin Sallings         *
3228ddc1418SDustin Sallings         * @param handle the engine handle
3238ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
3248ddc1418SDustin Sallings         * @param key the key to look up
3258ddc1418SDustin Sallings         * @param nkey the length of the key
3268ddc1418SDustin Sallings         * @param increment if true, increment the value, else decrement
3278ddc1418SDustin Sallings         * @param create if true, create the item if it's missing
3288ddc1418SDustin Sallings         * @param delta the amount to increment or decrement.
3298ddc1418SDustin Sallings         * @param initial when creating, specifies the initial value
3308ddc1418SDustin Sallings         * @param exptime when creating, specifies the expiration time
3318ddc1418SDustin Sallings         * @param cas output CAS value
3328ddc1418SDustin Sallings         * @param result output arithmetic value
333eeaeeedeSTrond Norbye         * @param vbucket the virtual bucket id
3348ddc1418SDustin Sallings         *
3358ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
3368ddc1418SDustin Sallings         */
33714785bd3SDustin Sallings        ENGINE_ERROR_CODE (*arithmetic)(ENGINE_HANDLE* handle,
33814785bd3SDustin Sallings                                        const void* cookie,
33914785bd3SDustin Sallings                                        const void* key,
34014785bd3SDustin Sallings                                        const int nkey,
34114785bd3SDustin Sallings                                        const bool increment,
34214785bd3SDustin Sallings                                        const bool create,
34314785bd3SDustin Sallings                                        const uint64_t delta,
34414785bd3SDustin Sallings                                        const uint64_t initial,
34514785bd3SDustin Sallings                                        const rel_time_t exptime,
34614785bd3SDustin Sallings                                        uint64_t *cas,
3471639b21aSabhinavdangeti                                        uint8_t datatype,
348eeaeeedeSTrond Norbye                                        uint64_t *result,
349eeaeeedeSTrond Norbye                                        uint16_t vbucket);
3508ddc1418SDustin Sallings
3518ddc1418SDustin Sallings        /**
3528ddc1418SDustin Sallings         * Flush the cache.
3538ddc1418SDustin Sallings         *
3548ddc1418SDustin Sallings         * @param handle the engine handle
3558ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
3568ddc1418SDustin Sallings         * @param when time at which the flush should take effect
3578ddc1418SDustin Sallings         *
3588ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
3598ddc1418SDustin Sallings         */
36014785bd3SDustin Sallings        ENGINE_ERROR_CODE (*flush)(ENGINE_HANDLE* handle,
36114785bd3SDustin Sallings                                   const void* cookie, time_t when);
36214785bd3SDustin Sallings
36314785bd3SDustin Sallings        /*
36414785bd3SDustin Sallings         * Statistics
36514785bd3SDustin Sallings         */
3668ddc1418SDustin Sallings
3678ddc1418SDustin Sallings        /**
3688ddc1418SDustin Sallings         * Get statistics from the engine.
3698ddc1418SDustin Sallings         *
3708ddc1418SDustin Sallings         * @param handle the engine handle
3718ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
3728ddc1418SDustin Sallings         * @param stat_key optional argument to stats
3738ddc1418SDustin Sallings         * @param nkey the length of the stat_key
3748ddc1418SDustin Sallings         * @param add_stat callback to feed results to the output
3758ddc1418SDustin Sallings         *
3768ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
3778ddc1418SDustin Sallings         */
37814785bd3SDustin Sallings        ENGINE_ERROR_CODE (*get_stats)(ENGINE_HANDLE* handle,
37914785bd3SDustin Sallings                                       const void* cookie,
38014785bd3SDustin Sallings                                       const char* stat_key,
38114785bd3SDustin Sallings                                       int nkey,
38214785bd3SDustin Sallings                                       ADD_STAT add_stat);
3838ddc1418SDustin Sallings
3848ddc1418SDustin Sallings        /**
3858ddc1418SDustin Sallings         * Reset the stats.
3868ddc1418SDustin Sallings         *
3878ddc1418SDustin Sallings         * @param handle the engine handle
3886c869215SDustin Sallings         * @param cookie The cookie provided by the frontend
3898ddc1418SDustin Sallings         */
3906c869215SDustin Sallings        void (*reset_stats)(ENGINE_HANDLE* handle, const void *cookie);
39114785bd3SDustin Sallings
392c3fd96d9SSean Lynch        /**
393d9be1f23STrond Norbye         * Get an array of per-thread stats. This allows the engine to
394d9be1f23STrond Norbye         * keep separate stats per cookie. Your implementation of this
395d9be1f23STrond Norbye         * callback <b>must</b> return a memory area returned from the
396d9be1f23STrond Norbye         * server API's new_stats. If all of your connections belong
397d9be1f23STrond Norbye         * to the same "stats pool" you should set this callback to
398d9be1f23STrond Norbye         * NULL.
399d9be1f23STrond Norbye         *
400d9be1f23STrond Norbye         * @param handle the engine handle
401d9be1f23STrond Norbye         * @param cookie the cookie representing the connection
402d9be1f23STrond Norbye         * @return A pointer to a stats structure (or NULL if allocation
403d9be1f23STrond Norbye         *         failed)
404c3fd96d9SSean Lynch         */
405a5479c51SSean Lynch        void *(*get_stats_struct)(ENGINE_HANDLE* handle,
406a5479c51SSean Lynch                                  const void* cookie);
407c3fd96d9SSean Lynch
408c3fd96d9SSean Lynch        /**
409d9be1f23STrond Norbye         * Aggregate stats among all per-connection stats. This allows
410d9be1f23STrond Norbye         * the engine to call the aggregation callback for a number of
411d9be1f23STrond Norbye         * stat structures. You would normally not use this if you
412d9be1f23STrond Norbye         * didn't implement a special get_stats_struct().
413d9be1f23STrond Norbye         *
414d9be1f23STrond Norbye         *
415d9be1f23STrond Norbye         * @param handle the engine handle
416d9be1f23STrond Norbye         * @param cookie the cookie representing the connection
417d9be1f23STrond Norbye         * @param callback the callback function you should call for all
418d9be1f23STrond Norbye         *        of the stats structures you want to include in the
419d9be1f23STrond Norbye         *        aggregatioin.
420d9be1f23STrond Norbye         * @param dest This is the second parameter to the callback
421d9be1f23STrond Norbye         *        function.
422d9be1f23STrond Norbye         * @return ENGINE_SUCCESS unless you had a failure
423d9be1f23STrond Norbye          */
424c3fd96d9SSean Lynch        ENGINE_ERROR_CODE (*aggregate_stats)(ENGINE_HANDLE* handle,
425c3fd96d9SSean Lynch                                             const void* cookie,
426a5479c51SSean Lynch                                             void (*callback)(void*, void*),
427a5479c51SSean Lynch                                             void*);
428c3fd96d9SSean Lynch
429c3fd96d9SSean Lynch
4308ddc1418SDustin Sallings        /**
4318ddc1418SDustin Sallings         * Any unknown command will be considered engine specific.
4328ddc1418SDustin Sallings         *
4338ddc1418SDustin Sallings         * @param handle the engine handle
4348ddc1418SDustin Sallings         * @param cookie The cookie provided by the frontend
4358ddc1418SDustin Sallings         * @param request pointer to request header to be filled in
4368ddc1418SDustin Sallings         * @param response function to transmit data
4378ddc1418SDustin Sallings         *
4388ddc1418SDustin Sallings         * @return ENGINE_SUCCESS if all goes well
43914785bd3SDustin Sallings         */
4408ddc1418SDustin Sallings        ENGINE_ERROR_CODE (*unknown_command)(ENGINE_HANDLE* handle,
4418ddc1418SDustin Sallings                                             const void* cookie,
4428ddc1418SDustin Sallings                                             protocol_binary_request_header *request,
4438ddc1418SDustin Sallings                                             ADD_RESPONSE response);
44472a52b14STrond Norbye
44584d6c30cSTrond Norbye        /* TAP operations */
44684d6c30cSTrond Norbye
44784d6c30cSTrond Norbye        /**
44884d6c30cSTrond Norbye         * Callback for all incoming TAP messages. It is up to the engine
44984d6c30cSTrond Norbye         * to determine what to do with the event. The core will create and send
45084d6c30cSTrond Norbye         * a TAP_ACK message if the flag section contains TAP_FLAG_SEND_ACK with
45184d6c30cSTrond Norbye         * the status byte mapped from the return code.
45284d6c30cSTrond Norbye         *
45384d6c30cSTrond Norbye         * @param handle the engine handle
45484d6c30cSTrond Norbye         * @param cookie identification for the tap stream
45584d6c30cSTrond Norbye         * @param engine_specific pointer to engine specific data (received)
45684d6c30cSTrond Norbye         * @param nengine_specific number of bytes of engine specific data
45784d6c30cSTrond Norbye         * @param ttl ttl for this item (Tap stream hops)
45884d6c30cSTrond Norbye         * @param tap_flags tap flags for this object
45984d6c30cSTrond Norbye         * @param tap_event the tap event from over the wire
46084d6c30cSTrond Norbye         * @param tap_seqno sequence number for this item
46184d6c30cSTrond Norbye         * @param key the key in the message
46284d6c30cSTrond Norbye         * @param nkey the number of bytes in the key
46384d6c30cSTrond Norbye         * @param flags the flags for the item
46484d6c30cSTrond Norbye         * @param exptime the expiry time for the object
46584d6c30cSTrond Norbye         * @param cas the cas for the item
46684d6c30cSTrond Norbye         * @param data the data for the item
46784d6c30cSTrond Norbye         * @param ndata the number of bytes in the object
468eeaeeedeSTrond Norbye         * @param vbucket the virtual bucket for the object
46984d6c30cSTrond Norbye         * @return ENGINE_SUCCESS for success
47084d6c30cSTrond Norbye         */
47184d6c30cSTrond Norbye        ENGINE_ERROR_CODE (*tap_notify)(ENGINE_HANDLE* handle,
47284d6c30cSTrond Norbye                                        const void *cookie,
47384d6c30cSTrond Norbye                                        void *engine_specific,
47484d6c30cSTrond Norbye                                        uint16_t nengine,
47584d6c30cSTrond Norbye                                        uint8_t ttl,
47684d6c30cSTrond Norbye                                        uint16_t tap_flags,
47784d6c30cSTrond Norbye                                        tap_event_t tap_event,
47884d6c30cSTrond Norbye                                        uint32_t tap_seqno,
47984d6c30cSTrond Norbye                                        const void *key,
48084d6c30cSTrond Norbye                                        size_t nkey,
48184d6c30cSTrond Norbye                                        uint32_t flags,
48284d6c30cSTrond Norbye                                        uint32_t exptime,
48384d6c30cSTrond Norbye                                        uint64_t cas,
4841639b21aSabhinavdangeti                                        uint8_t datatype,
48584d6c30cSTrond Norbye                                        const void *data,
486eeaeeedeSTrond Norbye                                        size_t ndata,
487eeaeeedeSTrond Norbye                                        uint16_t vbucket);
48884d6c30cSTrond Norbye
48984d6c30cSTrond Norbye        /**
49084d6c30cSTrond Norbye         * Get (or create) a Tap iterator for this connection.
49184d6c30cSTrond Norbye         * @param handle the engine handle
49284d6c30cSTrond Norbye         * @param cookie The connection cookie
49384d6c30cSTrond Norbye         * @param client The "name" of the client
49484d6c30cSTrond Norbye         * @param nclient The number of bytes in the client name
49584d6c30cSTrond Norbye         * @param flags Tap connection flags
49684d6c30cSTrond Norbye         * @param userdata Specific userdata the engine may know how to use
49784d6c30cSTrond Norbye         * @param nuserdata The size of the userdata
49884d6c30cSTrond Norbye         * @return a tap iterator to iterate through the event stream
49984d6c30cSTrond Norbye         */
50084d6c30cSTrond Norbye        TAP_ITERATOR (*get_tap_iterator)(ENGINE_HANDLE* handle, const void* cookie,
50184d6c30cSTrond Norbye                                         const void* client, size_t nclient,
50284d6c30cSTrond Norbye                                         uint32_t flags,
50384d6c30cSTrond Norbye                                         const void* userdata, size_t nuserdata);
50484d6c30cSTrond Norbye
50572a52b14STrond Norbye        /**
50672a52b14STrond Norbye         * Set the CAS id on an item.
50772a52b14STrond Norbye         */
50854d8e3c9SDustin Sallings        void (*item_set_cas)(ENGINE_HANDLE *handle, const void *cookie,
50954d8e3c9SDustin Sallings                             item *item, uint64_t cas);
51072a52b14STrond Norbye
51172a52b14STrond Norbye        /**
512679d682eSTrond Norbye         * Get information about an item.
513679d682eSTrond Norbye         *
514679d682eSTrond Norbye         * The loader of the module may need the pointers to the actual data within
515679d682eSTrond Norbye         * an item. Instead of having to create multiple functions to get each
516679d682eSTrond Norbye         * individual item, this function will get all of them.
517679d682eSTrond Norbye         *
518679d682eSTrond Norbye         * @param handle the engine that owns the object
51954d8e3c9SDustin Sallings         * @param cookie connection cookie for this item
520679d682eSTrond Norbye         * @param item the item to request information about
521679d682eSTrond Norbye         * @param item_info
522679d682eSTrond Norbye         * @return true if successful
5233b414bc7STrond Norbye         */
524679d682eSTrond Norbye        bool (*get_item_info)(ENGINE_HANDLE *handle,
52554d8e3c9SDustin Sallings                              const void *cookie,
526679d682eSTrond Norbye                              const item* item,
527679d682eSTrond Norbye                              item_info *item_info);
528eeaeeedeSTrond Norbye
5294688e0f4Sabhinavdangeti        /**
5304688e0f4Sabhinavdangeti         * Set information of an item.
5314688e0f4Sabhinavdangeti         *
5324688e0f4Sabhinavdangeti         * Set updated item information.
5334688e0f4Sabhinavdangeti         *
5344688e0f4Sabhinavdangeti         * @param handle the engine that owns the object
5354688e0f4Sabhinavdangeti         * @param cookie connection cookie for this item
5364688e0f4Sabhinavdangeti         * @param item the item who's information is to be updated
5374688e0f4Sabhinavdangeti         * @param item_info
5384688e0f4Sabhinavdangeti         * @return true if successful
5394688e0f4Sabhinavdangeti         */
5404688e0f4Sabhinavdangeti        bool (*set_item_info)(ENGINE_HANDLE *handle,
5414688e0f4Sabhinavdangeti                              const void *cookie,
5424688e0f4Sabhinavdangeti                              item* item,
5434688e0f4Sabhinavdangeti                              const item_info *itm_info);
544eeaeeedeSTrond Norbye
545eeaeeedeSTrond Norbye        /**
546eeaeeedeSTrond Norbye         * Get extra error information for an operation.
547eeaeeedeSTrond Norbye         *
548eeaeeedeSTrond Norbye         * @param handle the engine handle
549eeaeeedeSTrond Norbye         * @param cookie The connection cookie
550eeaeeedeSTrond Norbye         * @param buffer Where to store the info
551eeaeeedeSTrond Norbye         * @param buffsz The size of the buffer
552eeaeeedeSTrond Norbye         * @return the number of bytes written to the buffer
553eeaeeedeSTrond Norbye         */
554eeaeeedeSTrond Norbye        size_t (*errinfo)(ENGINE_HANDLE *handle, const void* cookie,
555eeaeeedeSTrond Norbye                          char *buffer, size_t buffsz);
556eeaeeedeSTrond Norbye
557288d1a8bSTrond Norbye        /**
558288d1a8bSTrond Norbye         * Get the vbucket map stored in the engine
559288d1a8bSTrond Norbye         *
560288d1a8bSTrond Norbye         * @param handle the engine handle
561288d1a8bSTrond Norbye         * @param cookie The connection cookie
562288d1a8bSTrond Norbye         * @param callback a function the engine may call to "return" the
563288d1a8bSTrond Norbye         *                 buffer.
564288d1a8bSTrond Norbye         * @return ENGINE_SUCCESS for success
565288d1a8bSTrond Norbye         */
566288d1a8bSTrond Norbye        ENGINE_ERROR_CODE (*get_engine_vb_map)(ENGINE_HANDLE* handle,
567288d1a8bSTrond Norbye                                               const void * cookie,
568288d1a8bSTrond Norbye                                               engine_get_vb_map_cb callback);
569eeaeeedeSTrond Norbye
570f1818198STrond Norbye        struct dcp_interface dcp;
57114785bd3SDustin Sallings    } ENGINE_HANDLE_V1;
5722466734eSTrond Norbye
57302ae1f50SDustin Sallings    /**
57402ae1f50SDustin Sallings     * @}
57502ae1f50SDustin Sallings     */
5762466734eSTrond Norbye#ifdef __cplusplus
5772466734eSTrond Norbye}
5782466734eSTrond Norbye#endif
5792466734eSTrond Norbye
5802466734eSTrond Norbye#endif