NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EVENTS
SEE ALSO

NAME

pmemset_config_set_event_callback() - set an event callback

SYNOPSIS

#include <libpmemset.h>
#define PMEMSET_EVENT_CONTEXT_SIZE (64)
struct pmemset_event_context {
	enum pmemset_event type;
	union {
		char _data[PMEMSET_EVENT_CONTEXT_SIZE];
		struct pmemset_event_copy copy;
		struct pmemset_event_move move;
		struct pmemset_event_set set;
		struct pmemset_event_flush flush;
		struct pmemset_event_drain drain;
		struct pmemset_event_persist persist;
		struct pmemset_event_bad_block bad_block;
		struct pmemset_event_part_remove part_remove;
		struct pmemset_event_part_add part_add;
	} data;
};

typedef int pmemset_event_callback(struct pmemset *set,
        struct pmemset_event_context *ctx,
        void *arg);

void pmemset_config_set_event_callback(struct pmemset_config *cfg,
		pmemset_event_callback *callback, void *arg);

DESCRIPTION

The pmemset_config_set_event_callback() sets an user provided callback in cfg. arg will be passed to the callback each time it will be called by the library.

The callback will be called by pmemset each time an event occurs. Events are only fired during the user’s calls of the libpmemset(7) methods. The detailed list of events and its description can be found in Events section below. The callback function should return 0 in case of success. If the event supports error handling, the callback can return a non-zero value in case of error, otherwise return value is ignored. Struct pmemset_event_context is a tagged union, which contains all event structures, in libpmemset(7). The type field contains information of the type of the event fired, where the data union contains event-specific information.

There’s no guarantee that accessing pointers in ctx inside of the callback is thread-safe. The library user must guarantee this by not having multiple threads accessing the same region on the set. Once the function exits ctx and its data are invalid.

RETURN VALUE

The pmemset_config_set_event_callback() returns no value.

EVENTS

• PMEMSET_EVENT_PART_ADD - occurs for each new part added to the pmemset using pmemset_part_map(3) function.

struct pmemset_event_flush {
	void *addr;
	size_t len;
};

PMEMSET_EVENT_FLUSH is fired before pmemset_flush(3) or pmemset_persist(3) completes its work. The flush field in data union contains addr and len passed to those functions. This event doesn’t support error handling, which means that the value returned by the callback function is ignored.

PMEMSET_EVENT_DRAIN is fired after pmemset_drain(3) or pmemset_persist(3) completes its work. In case of pmemset_persist(3) this event is fired after PMEMSET_EVENT_FLUSH. This event doesn’t support error handling, which means that the value returned by the callback function is ignored.

struct pmemset_event_copy {
	void *src;
	void *dest;
	size_t len;
	unsigned flags;
};

struct pmemset_event_move {
	void *src;
	void *dest;
	size_t len;
	unsigned flags;
};

struct pmemset_event_set {
	void *dest;
	int value;
	size_t len;
	unsigned flags;
};

PMEMSET_EVENT_COPY, PMEMSET_EVENT_MOVE, PMEMSET_EVENT_SET are fired, respectively, before pmemset_memcpy(3), pmemset_memmove(3), pmemset_memset(3) completed its work. Similarly, copy, move, or set fields in the data union contain all arguments passed to these functions. If PMEMSET_F_MEM_NODRAIN flag is not passed to these functions, a single PMEMSET_EVENT_DRAIN will be fired on the end of opperation. During these functions “flush” and “drain” operations are performed, but they will not trigger any additional events. PMEMSET_EVENT_FLUSH and PMEMSET_EVENT_DRAIN This event doesn’t support error handling, which means that the value returned by the callback function is ignored.

SEE ALSO

pmemset_part_map, libpmem2(7), libpmemset(7) and http://pmem.io