picotm-module.h File Reference

Picotm's module interface. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "compiler.h"
#include "picotm-error.h"

Include dependency graph for picotm-module.h:

Typedefs
typedef void(*	picotm_module_lock_function) (void *data, struct picotm_error *error)
typedef void(*	picotm_module_unlock_function) (void *data, struct picotm_error *error)
typedef bool(*	picotm_module_is_valid_function) (void *data, int is_irrevocable, struct picotm_error *error)
typedef void(*	picotm_module_apply_function) (void *data, struct picotm_error *error)
typedef void(*	picotm_module_undo_function) (void *data, struct picotm_error *error)
typedef void(*	picotm_module_apply_events_function) (const struct picotm_event *events, size_t nevents, void *data, struct picotm_error *error)
typedef void(*	picotm_module_undo_events_function) (const struct picotm_event *events, size_t nevents, void *data, struct picotm_error *error)
typedef void(*	picotm_module_update_cc_function) (void *data, int is_irrevocable, struct picotm_error *error)
typedef void(*	picotm_module_clear_cc_function) (void *data, int is_irrevocable, struct picotm_error *error)
typedef void(*	picotm_module_finish_function) (void *data, struct picotm_error *error)
typedef void(*	picotm_module_uninit_function) (void *data)
typedef int(*	picotm_tabwalk_1_function) (void *data0)
typedef int(*	picotm_tabwalk_2_function) (void *data0, void *data1)
typedef int(*	picotm_tabwalk_3_function) (void *data0, void *data1, void *data2)
typedef int(*	picotm_tab_compare_function) (const void *data0, const void *data1)

Functions
PICOTM_NOTHROW unsigned long	picotm_register_module (picotm_module_lock_function lock, picotm_module_unlock_function unlock, picotm_module_is_valid_function is_valid, picotm_module_apply_function apply, picotm_module_undo_function undo, picotm_module_apply_events_function apply_events, picotm_module_undo_events_function undo_events, picotm_module_update_cc_function update_cc, picotm_module_clear_cc_function clear_cc, picotm_module_finish_function finish, picotm_module_uninit_function uninit, void *cbdata, struct picotm_error *error)
PICOTM_NOTHROW void	picotm_append_event (unsigned long module, unsigned long op, uintptr_t cookie, struct picotm_error *error)
PICOTM_NOTHROW void	picotm_resolve_conflict (struct picotm_tx *conflicting_tx)
PICOTM_NOTHROW void	picotm_recover_from_error_code (enum picotm_error_code error_hint)
PICOTM_NOTHROW void	picotm_recover_from_errno (int errno_hint)
PICOTM_NOTHROW void	picotm_recover_from_error (const struct picotm_error *error)
PICOTM_NOTHROW bool	picotm_is_valid (void)
PICOTM_NOTHROW void	picotm_irrevocable (void)
PICOTM_NOTHROW bool	picotm_is_irrevocable (void)
PICOTM_NOTHROW void *	picotm_tabresize (void *base, size_t nelems, size_t newnelems, size_t siz)
PICOTM_NOTHROW void	picotm_tabfree (void *base)
PICOTM_NOTHROW int	picotm_tabwalk_1 (void *base, size_t nelems, size_t siz, picotm_tabwalk_1_function walk)
PICOTM_NOTHROW int	picotm_tabwalk_2 (void *base, size_t nelems, size_t siz, picotm_tabwalk_2_function walk, void *data)
PICOTM_NOTHROW int	picotm_tabwalk_3 (void *base, size_t nelems, size_t siz, picotm_tabwalk_3_function walk, void *data1, void *data2)
PICOTM_NOTHROW int	picotm_tabrwalk_1 (void *base, size_t nelems, size_t siz, picotm_tabwalk_1_function walk)
PICOTM_NOTHROW int	picotm_tabrwalk_2 (void *base, size_t nelems, size_t siz, picotm_tabwalk_2_function walk, void *data)
PICOTM_NOTHROW size_t	picotm_tabuniq (void *base, size_t nelems, size_t siz, picotm_tab_compare_function compare)

Detailed Description

Picotm is extensible. The header file picotm-module.h contains the declaration of picotm's module interface. The interface allows for implementing support for additional features, libraries and functionality. All existing modules are written on top of this interface as well.

Typedef Documentation

picotm_module_apply_events_function

typedef void(* picotm_module_apply_events_function) (const struct picotm_event *events, size_t nevents, void *data, struct picotm_error *error)

Invoked by picotm during the commit phase to apply a number of consecutive events.

Parameters

	events	An array of events.
	nevents	The number of elements in events.
	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_apply_function

typedef void(* picotm_module_apply_function) (void *data, struct picotm_error *error)

Invoked by picotm during the commit phase to apply changes of a module.

Parameters

	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_clear_cc_function

typedef void(* picotm_module_clear_cc_function) (void *data, int is_irrevocable, struct picotm_error *error)

Invoked by picotm to clear a module's concurrency control during an abort.

Parameters

	data	The pointer to module-specific data.
	is_irrevocable	True if the transaction is irrevocable, false otherwise.
[out]	error	Returns an error from the module.

picotm_module_finish_function

typedef void(* picotm_module_finish_function) (void *data, struct picotm_error *error)

Invoked by picotm to clean up a module's resources at the end of a transaction.

Parameters

	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_is_valid_function

typedef bool(* picotm_module_is_valid_function) (void *data, int is_irrevocable, struct picotm_error *error)

Invoked by picotm to validate a module's resources.

Parameters

	data	The pointer to module-specific data.
	is_irrevocable	True if the transaction is irrevocable, false otherwise.
[out]	error	Returns an error from the module.

Returns

True if valid, or flase otherwise.

picotm_module_lock_function

typedef void(* picotm_module_lock_function) (void *data, struct picotm_error *error)

Invoked by picotm to lock a module's resources at the beginning if a commit.

Parameters

	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_undo_events_function

typedef void(* picotm_module_undo_events_function) (const struct picotm_event *events, size_t nevents, void *data, struct picotm_error *error)

Invoked by picotm during the roll-back phase to revert a number of consecutive events.

Parameters

	events	An array of events.
	nevents	The number of elements in events.
	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_undo_function

typedef void(* picotm_module_undo_function) (void *data, struct picotm_error *error)

Invoked by picotm during the roll-back phase to revert changes of a module.

Parameters

	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_uninit_function

typedef void(* picotm_module_uninit_function) (void *data)

Invoked by picotm to clean up a module's resources when the thread exists.

Parameters

data	The pointer to module-specific data.

picotm_module_unlock_function

typedef void(* picotm_module_unlock_function) (void *data, struct picotm_error *error)

Invoked by picotm to unlock a module's resources. This is the inverse of picotm_module_lock_function.

Parameters

	data	The pointer to module-specific data.
[out]	error	Returns an error from the module.

picotm_module_update_cc_function

typedef void(* picotm_module_update_cc_function) (void *data, int is_irrevocable, struct picotm_error *error)

Invoked by picotm to update a module's concurrency control during a commit.

Parameters

	data	The pointer to module-specific data.
	is_irrevocable	True if the transaction is irrevocable, false otherwise.
[out]	error	Returns an error from the module.

picotm_tab_compare_function

typedef int(* picotm_tab_compare_function) (const void *data0, const void *data1)

Invoked by table functions for comparing two elements.

Parameters

data0	A table element.
data1	A table element.

Returns

-1, 0, or 1 if data0 is less, equal, or greatet than data1.

picotm_tabwalk_1_function

typedef int(* picotm_tabwalk_1_function) (void *data0)

Invoked by table functions when walking over the elements of a table.

Parameters

data0

The table element.

Returns

The number of element to advance on success, or a negative value otherwise.

picotm_tabwalk_2_function

typedef int(* picotm_tabwalk_2_function) (void *data0, void *data1)

Invoked by table functions when walking over the elements of a table.

Parameters

data0	The table element.
data1	An additional argument.

Returns

The number of element to advance on success, or a negative value otherwise.

picotm_tabwalk_3_function

typedef int(* picotm_tabwalk_3_function) (void *data0, void *data1, void *data2)

Invoked by table functions when walking over the elements of a table.

Parameters

data0	The table element.
data1	An additional argument.
data2	An additional argument.

Returns

The number of element to advance on success, or a negative value otherwise.

Function Documentation

picotm_append_event()

PICOTM_NOTHROW void picotm_append_event	(	unsigned long	module,
		unsigned long	op,
		uintptr_t	cookie,
		struct picotm_error *	error
	)

Appends an event to the transaction's event log.

Parameters

	module	The module number
	op	A module-specific operation.
	cookie	A module-specific cookie.
[out]	error	Returns an error.

picotm_irrevocable()

PICOTM_NOTHROW void picotm_irrevocable

(

void

)

Makes the current transaction irrevocable.

picotm_is_irrevocable()

PICOTM_NOTHROW bool picotm_is_irrevocable

(

void

)

Returns the transaction irrevocability status.

Returns

True if the transaction is irrevocable, false otherwise.

picotm_is_valid()

PICOTM_NOTHROW bool picotm_is_valid

(

void

)

Validates the transaction state.

Returns

True if the transaction state is valid, false otherwise.

picotm_recover_from_errno()

PICOTM_NOTHROW void picotm_recover_from_errno

(

int

errno_hint

)

Instructs the transaction management system to recover from an error. The errno code is given as a hint.

Parameters

errno_hint

The errno code of the detected error, or 0 if unknown.

Attention

This function will not return if picotm aborts the transaction. If the function returns, the caller shall restart the operation that triggered the conflict.

picotm_recover_from_error()

PICOTM_NOTHROW void picotm_recover_from_error

(

const struct picotm_error *

error

)

Instructs the transaction management system to recover from an error. The error is supplied as an argument.

Parameters

error

The detected error.

Attention

This function will not return if picotm aborts the transaction. If the function returns, the caller shall restart the operation that triggered the conflict.

picotm_recover_from_error_code()

PICOTM_NOTHROW void picotm_recover_from_error_code

(

enum picotm_error_code

error_hint

)

Instructs the transaction management system to recover from an error. The error code is given as a hint.

Parameters

error_hint

The error code of the detected error, or PICOTM_GENERAL_ERROR if unknown.

Attention

This function will not return if picotm aborts the transaction. If the function returns, the caller shall restart the operation that triggered the conflict.

picotm_register_module()

PICOTM_NOTHROW unsigned long picotm_register_module	(	picotm_module_lock_function	lock,
		picotm_module_unlock_function	unlock,
		picotm_module_is_valid_function	is_valid,
		picotm_module_apply_function	apply,
		picotm_module_undo_function	undo,
		picotm_module_apply_events_function	apply_events,
		picotm_module_undo_events_function	undo_events,
		picotm_module_update_cc_function	update_cc,
		picotm_module_clear_cc_function	clear_cc,
		picotm_module_finish_function	finish,
		picotm_module_uninit_function	uninit,
		void *	cbdata,
		struct picotm_error *	error
	)

Registers a new module with the transaction management system.

Parameters

	lock	The lock call-back function.
	unlock	The unlock call-back function.
	is_valid	The is-valid call-back function.
	apply	The apply call-back function.
	undo	The undo call-back function.
	apply_events	The apply-events call-back function.
	undo_events	The undo-events call-back function.
	update_cc	The update-CC call-back function.
	clear_cc	The clear-CC call-back function.
	finish	The finish call-back function.
	uninit	The uninit call-back function.
	cbdata	A pointer to module-specific data.
[out]	error	Returns an error.

Returns

A module number on success.

picotm_resolve_conflict()

PICOTM_NOTHROW void picotm_resolve_conflict

(

struct picotm_tx *

conflicting_tx

)

Instructs the transaction management system to resolve a conflict with another transaction.

Parameters

conflicting_tx

The conflicting transaction, or NULL if unknown.

Attention

This function will not return if picotm aborts the transaction. If the function returns, the caller shall restart the operation that triggered the conflict.

picotm_tabfree()

PICOTM_NOTHROW void picotm_tabfree

(

void *

base

)

Free table memory.

Parameters

base	A pointer to the table's first element.

picotm_tabresize()

PICOTM_NOTHROW void* picotm_tabresize	(	void *	base,
		size_t	nelems,
		size_t	newnelems,
		size_t	siz
	)

Allocate or resize table.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
newnelems	The new number of elements in the table.
siz	The number of bytes per element.

Returns

A pointer to the resized table on success, or NULL otherwise.

picotm_tabrwalk_1()

PICOTM_NOTHROW int picotm_tabrwalk_1	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tabwalk_1_function	walk
	)

Walk over table in reversed order.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
walk	The call-back function.

Returns

0 on success, or a negative value otherwise.

picotm_tabrwalk_2()

PICOTM_NOTHROW int picotm_tabrwalk_2	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tabwalk_2_function	walk,
		void *	data
	)

Walk over table in reversed order.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
walk	The call-back function.
data	An additional second argument to the call-back function.

Returns

0 on success, or a negative value otherwise.

picotm_tabuniq()

PICOTM_NOTHROW size_t picotm_tabuniq	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tab_compare_function	compare
	)

Filters out duplicate elements

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
compare	The call-back function for comparing elements.

Returns

The new number of elements in the table.

picotm_tabwalk_1()

PICOTM_NOTHROW int picotm_tabwalk_1	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tabwalk_1_function	walk
	)

Walk over table elements.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
walk	The call-back function.

Returns

0 on success, or a negative value otherwise.

picotm_tabwalk_2()

PICOTM_NOTHROW int picotm_tabwalk_2	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tabwalk_2_function	walk,
		void *	data
	)

Walk over table elements.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
walk	The call-back function.
data	An additional second argument to the call-back function.

Returns

0 on success, or a negative value otherwise.

picotm_tabwalk_3()

PICOTM_NOTHROW int picotm_tabwalk_3	(	void *	base,
		size_t	nelems,
		size_t	siz,
		picotm_tabwalk_3_function	walk,
		void *	data1,
		void *	data2
	)

Walk over table elements.

Parameters

base	A pointer to the table's first element.
nelems	The number of elements in the table.
siz	The number of bytes per element.
walk	The call-back function.
data1	An additional second argument to the call-back function.
data2	An additional third argument to the call-back function.

Returns

0 on success, or a negative value otherwise.