The Pointer-Data Module

The pointer-data module associates data items with arbitrary memory locations. The data can be stored globally or local to the thread. More...

Files
file	picotm-ptrdata.h
	Public interfaces of picotm's pointer-data module.

Functions
PICOTM_NOTHROW void	ptr_clear_data (const void *ptr, struct picotm_error *error)
PICOTM_NOTHROW void	ptr_clear_shared_data (const void *ptr, struct picotm_error *error)
PICOTM_NOTHROW void *	ptr_get_data (const void *ptr, struct picotm_error *error)
PICOTM_NOTHROW void *	ptr_get_shared_data (const void *ptr, struct picotm_error *error)
PICOTM_NOTHROW void	ptr_set_data (const void *ptr, const void *data, struct picotm_error *error)
PICOTM_NOTHROW void	ptr_set_shared_data (const void *ptr, const void *data, struct picotm_error *error)
PICOTM_NOTHROW _Bool	ptr_test_and_set_shared_data (const void *ptr, const void *current, const void *data, struct picotm_error *error)

Detailed Description

The pointer-data module associates data items with arbitrary memory locations. The data can be stored globally or local to the thread. The pointer-data module is a helper for other module and not to be used directly in application transactions.

Thread-local data is associated with an address with ptr_set_data().

void* ptr = create_a_ptr_data_structure();

int* data = malloc(sizeof(int));
*data = 0x1234;

struct picotm_error error = PICOTM_ERROR_INITIALIZER;
ptr_set_data(ptr, data, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}

Once set, the data can be queried with ptr_get_data().

struct picotm_error error = PICOTM_ERROR_INITIALIZER;
int* data = ptr_get_data(ptr, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}

By default, the value returned by ptr_get_data()is NULL for address without data. Data can be cleared with a call to ptr_clear_data().

struct picotm_error error = PICOTM_ERROR_INITIALIZER;

int* data = ptr_get_data(ptr, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}
ptr_clear_data(ptr, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}

free(data);

This call resets the address' data to NULL. It's equivalent to ptr_set_data() with a data value of NULL, but faster if address has no data already associated with it. The function only clears the entry, the associated data itself has to be cleaned up by the caller.

For globally shared data, a similar interface exists. Data is globally associated with an address with ptr_set_shared_data(), retrieved with ptr_get_shared_data(), and cleared with ptr_clear_shared_data().

struct picotm_error error = PICOTM_ERROR_INITIALIZER;

void* ptr = create_a_ptr_data_structure();

int* data = malloc(sizeof(int));
*data = 0x1234;

ptr_set_shared_data(ptr, data, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}
int* data = ptr_get_shared_data(ptr, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}
ptr_clear_shared_data(ptr, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}

free(data);

All shared operations are atomic. If multiple threads try to set an address' data concurrently, exactly one will succeed. The atomic test-and-set function ptr_test_and_set_shared_data() is available. The example below replaces an address data only if the current data is NULL.

struct picotm_error error = PICOTM_ERROR_INITIALIZER;

void* ptr = create_a_ptr_data_structure();

int* data = malloc(sizeof(int));
*data = 0x1234;

succ = ptr_test_and_set_shared_data(ptr, NULL, data, &error);
if (picotm_error_is_set(&error)) {
    // handle error
}
if (succ) {
    // NULL has been replaced by the value of data
} else {
    // the previous non-NULL value remained in place
}

The pointer-data module does not clean up data value at the end of a thread of the application. Its using modules are responsible for this.

Function Documentation

ptr_clear_data()

PICOTM_NOTHROW void ptr_clear_data	(	const void *	ptr,
		struct picotm_error *	error
	)

Removes thread-local data from an address.

Parameters

	ptr	The address
[out]	error	Returns an error to the caller.

ptr_clear_shared_data()

PICOTM_NOTHROW void ptr_clear_shared_data	(	const void *	ptr,
		struct picotm_error *	error
	)

Removes shared data from an address.

Parameters

	ptr	The address
[out]	error	Returns an error to the caller.

ptr_get_data()

PICOTM_NOTHROW void* ptr_get_data	(	const void *	ptr,
		struct picotm_error *	error
	)

Returns thread-local data of an address.

Parameters

	ptr	The address
[out]	error	Returns an error to the caller.

ptr_get_shared_data()

PICOTM_NOTHROW void* ptr_get_shared_data	(	const void *	ptr,
		struct picotm_error *	error
	)

Returns shared data of an address.

Parameters

	ptr	The address
[out]	error	Returns an error to the caller.

ptr_set_data()

PICOTM_NOTHROW void ptr_set_data	(	const void *	ptr,
		const void *	data,
		struct picotm_error *	error
	)

Sets thread-local data for an address.

Parameters

	ptr	The address
	data	The address' data
[out]	error	Returns an error to the caller.

ptr_set_shared_data()

PICOTM_NOTHROW void ptr_set_shared_data	(	const void *	ptr,
		const void *	data,
		struct picotm_error *	error
	)

Sets shared data for an address.

Parameters

	ptr	The address
	data	The address' data
[out]	error	Returns an error to the caller.

ptr_test_and_set_shared_data()

PICOTM_NOTHROW _Bool ptr_test_and_set_shared_data	(	const void *	ptr,
		const void *	current,
		const void *	data,
		struct picotm_error *	error
	)

Sets shared data for an address if the address has the expected data value set.

Parameters

	ptr	The address
	current	The address' expected data
	data	The address' new data
[out]	error	Returns an error to the caller.

Returns

Returns true on success, or false otherwise.