Module caching functionality

Data Structures
struct	_userinfo
	Defines the functions required to support userdata preservation. More...

Functions
void	deregister_userdata_funcs (unsigned int id)
	Deregister a set of functions that handled a specific id. More...
void	register_userdata_funcs (userinfo_t *user)
	Register a set of functions to handle a specific id. More...
void *	symbol_get_userdata (const char *name, unsigned int id)
	Retrieve module specific data for a given symbol and unique id. More...
void	symbol_remove_alluserdata (const char *wildcard, unsigned int id, void(*dataremover)(void *data))
	Delete all userdata associated with a particular id for a group of symbols. More...
void	symbol_remove_userdata (const char *name, unsigned int id)
	Remove userdata for a given symbol and unique id. More...
void	symbol_set_userdata (const char *name, unsigned int id, void *ptr)
	Register a piece of data against a particular symbol and unique id. More...

Detailed Description

Module specific data can be associated with symbols within the Transformer core memory, this removes the need for each module to implement its own caching routines.

Each module's data is identified by a unique id supplied by the module, this permits modules to share data should that be desired.

A module should register a set of handling functions for their own unique id, this permits the automatic saving and loading to the memory file. Failure to register a set of functions may well result in a memory leak if the symbol is deleted since the module may not be informed unless it has registered an interest in it.

Function Documentation

void deregister_userdata_funcs

(

unsigned int

id

)

Deregister a set of functions that handled a specific id.

Parameters

id	Unique id to deregister functions for

void register_userdata_funcs

(

userinfo_t *

user

)

Register a set of functions to handle a specific id.

Parameters

user	A userinfo_t pointer which is correctly populated

This function copies the contents of the userinfo_t and hence it is not possible to dynamically change handling functions.

Furthermore, calling this function again with the same user->id without previously calling deregister_userdata_funcs() will result in undefined behaviour

void* symbol_get_userdata	(	const char *	name,
		unsigned int	id
	)

Retrieve module specific data for a given symbol and unique id.

Parameters

name	Symbol name
id	Unique id to retrieve data for

Returns

The void pointer that was previously register with symbol_set_userdata()

void symbol_remove_alluserdata	(	const char *	wildcard,
		unsigned int	id,
		void(*)(void *data)	dataremover
	)

Delete all userdata associated with a particular id for a group of symbols.

Parameters

wildcard	Pattern to remove data for
id	Unique id to remove data for
dataremover	A function to be called to remove the data

The pattern is the same specification as for symbol_match() and register_interest().

void symbol_remove_userdata	(	const char *	name,
		unsigned int	id
	)

Remove userdata for a given symbol and unique id.

Parameters

name	Symbol to remove data for
id	Unique id to remove data for

This function assumes that the module has already deallocated the data that is registered under this id. The typical usage of this function is as follows:

symbol_set_userdata("/DEMO/VOD.L",0x10,strdup("data"));

....

void  *data = symbol_get_userdata("/DEMO/VOD.L",0x10);

free(data);

symbol_remove_userdata("/DEMO/VOD.L",0x10);

void symbol_set_userdata	(	const char *	name,
		unsigned int	id,
		void *	ptr
	)

Register a piece of data against a particular symbol and unique id.

Parameters

name	Symbolname to register for
id	Unique id to register for
ptr	Generic pointer to register against the symbol/id combination