Data Structures | Typedefs | Functions
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"

Data Structures

struct  picotm_module_ops
 

Typedefs

typedef void(* picotm_module_apply_event_function) (uint16_t head, uintptr_t tail, void *data, struct picotm_error *error)
 
typedef void(* picotm_module_apply_function) (void *data, 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_lock_function) (void *data, struct picotm_error *error)
 
typedef void(* picotm_module_undo_event_function) (uint16_t head, uintptr_t tail, void *data, struct picotm_error *error)
 
typedef void(* picotm_module_undo_function) (void *data, struct picotm_error *error)
 
typedef void(* picotm_module_uninit_function) (void *data)
 
typedef void(* picotm_module_unlock_function) (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_validate_function) (void *data, int is_irrevocable, struct picotm_error *error)
 

Functions

PICOTM_NOTHROW void picotm_append_event (unsigned long module, uint16_t head, uintptr_t tail, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_irrevocable (void)
 
PICOTM_NOTHROW bool picotm_is_irrevocable (void)
 
PICOTM_NOTHROW bool picotm_is_valid (void)
 
PICOTM_NOTHROW void picotm_recover_from_errno (int errno_hint)
 
PICOTM_NOTHROW void picotm_recover_from_error (const struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_recover_from_error_code (enum picotm_error_code error_hint)
 
PICOTM_NOTHROW void picotm_recover_from_kern_return_t (kern_return_t value)
 
PICOTM_NOTHROW unsigned long picotm_register_module (const struct picotm_module_ops *ops, void *data, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_resolve_conflict (struct picotm_rwlock *conflicting_lock)
 

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_event_function

typedef void(* picotm_module_apply_event_function) (uint16_t head, uintptr_t tail, void *data, struct picotm_error *error)

Invoked by picotm during the commit phase to apply an event.

Parameters
headThe event's head data.
tailThe event's tail data.
dataThe pointer to module-specific data.
[out]errorReturns 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
dataThe pointer to module-specific data.
[out]errorReturns 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
dataThe pointer to module-specific data.
is_irrevocableTrue if the transaction is irrevocable, false otherwise.
[out]errorReturns 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
dataThe pointer to module-specific data.
[out]errorReturns an error from the module.

◆ 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
dataThe pointer to module-specific data.
[out]errorReturns an error from the module.

◆ picotm_module_undo_event_function

typedef void(* picotm_module_undo_event_function) (uint16_t head, uintptr_t tail, void *data, struct picotm_error *error)

Invoked by picotm during the roll-back phase to revert an event.

Parameters
headThe event's head data.
tailThe event's tail data.
dataThe pointer to module-specific data.
[out]errorReturns 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
dataThe pointer to module-specific data.
[out]errorReturns 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
dataThe 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
dataThe pointer to module-specific data.
[out]errorReturns 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
dataThe pointer to module-specific data.
is_irrevocableTrue if the transaction is irrevocable, false otherwise.
[out]errorReturns an error from the module.

◆ picotm_module_validate_function

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

Invoked by picotm to validate a module's resources.

Parameters
dataThe pointer to module-specific data.
is_irrevocableTrue if the transaction is irrevocable, false otherwise.
[out]errorReturns an error from the module.

Function Documentation

◆ picotm_append_event()

PICOTM_NOTHROW void picotm_append_event ( unsigned long  module,
uint16_t  head,
uintptr_t  tail,
struct picotm_error error 
)

Appends an event to the transaction's event log.

Parameters
moduleThe module number
headModule-specific head data.
tailModule-specific tail data, or a pointer to tail data.
[out]errorReturns 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_hintThe 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
errorThe 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_hintThe 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_recover_from_kern_return_t()

PICOTM_NOTHROW void picotm_recover_from_kern_return_t ( kern_return_t  value)

Instructs the transaction management system to recover from an error given as value of type 'kern_return_t'.

Parameters
valueThe kern_return_t value of 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_register_module()

PICOTM_NOTHROW unsigned long picotm_register_module ( const struct picotm_module_ops ops,
void *  data,
struct picotm_error error 
)

Registers a new module with the transaction management system.

Parameters
opsThe module-operations call-back structure.
dataA pointer to module-specific data.
[out]errorReturns an error.
Returns
A module number on success.

◆ picotm_resolve_conflict()

PICOTM_NOTHROW void picotm_resolve_conflict ( struct picotm_rwlock conflicting_lock)

Instructs the transaction management system to resolve a conflict between transactions.

Parameters
conflicting_lockThe conflicting lock, 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.