Detailed Description

A data file initialised in a structure.

Terms

Get : returns an immutable data set that must be released when the caller is finished with it.

Release : releases a reference on the data set returned from the Get operation.

Reload : reloads an existing data set while maintaining any current references to the existing data set.

Introduction

A DataSet is a data file initialised in a structure that can be used to process data. Collections from the file may be stored in memory or streamed from the file when needed.

A DataSet is used to process data, in most cases this is in the form of evidence. Values for the Properties which the data set is capable of returning can then be retrieved from the result of processing.

Creation

A DataSet is created by allocating the structure and initialising from one of the following:

File : a data file is either read into memory or handle maintained for streaming by the data set.

Memory : a data file read into continuous memory is used by the data set.

Operation

A DataSet is a resource to be maintained by a Resource Manager. So any thread wanting to use it must get a reference from the manager (see resource.h).

The data set implementation extending will contain methods to process data. Usually these will return a Results instance (or an extending structure), see results.h for more details.

Reloading

A DataSet can be reloaded without interrupting operation by using the defined Reload methods. These take either a new data file or a new memory pointer, initialise a new data set, and replace the existing one in a thread-safe manor.

Free

A DataSet is a managed resource, so it should not be freed directly. Instead the manager should be freed, so that the data set is safely freed without impacting other threads.

Collaboration diagram for Data Set:

Structs
struct	fiftyoneDegreesDataSetBase
	Base data set structure which contains the 'must have's for all data sets. More...

Macros
#define	FIFTYONE_DEGREES_DATASET_RELOAD(t)
	Reload functions are common across all data set implementations where the naming of the data set type and the init methods comform to the common pattern.

Typedefs
typedef fiftyoneDegreesStatusCode(*	fiftyoneDegreesDataSetInitFromMemoryMethod) (void dataSet, const void config, fiftyoneDegreesPropertiesRequired properties, void memory, fiftyoneDegreesFileOffset size, fiftyoneDegreesException *exception)
	Initialses the data set from data stored in continuous memory.
typedef fiftyoneDegreesStatusCode(*	fiftyoneDegreesDataSetInitFromFileMethod) (void dataSet, const void config, fiftyoneDegreesPropertiesRequired properties, const char fileName, fiftyoneDegreesException *exception)
	Initialses the data set from data stored on file.

Functions
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetInitProperties (fiftyoneDegreesDataSetBase dataSet, fiftyoneDegreesPropertiesRequired properties, void *state, fiftyoneDegreesPropertiesGetMethod getPropertyMethod, fiftyoneDegreesEvidencePropertiesGetMethod getEvidencePropertiesMethod)
	Initialises the properties in the data set.
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetInitHeaders (fiftyoneDegreesDataSetBase dataSet, void state, fiftyoneDegreesHeadersGetMethod getHeaderMethod, fiftyoneDegreesException *exception)
	Initialises the HTTP headers in the data set.
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetInitFromFile (fiftyoneDegreesDataSetBase dataSet, const char fileName, fiftyoneDegreesFileOffset bytesToCompare)
	Initialses the data set from data stored on file.
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetInitInMemory (fiftyoneDegreesDataSetBase dataSet, fiftyoneDegreesMemoryReader reader)
	Initialses the data set from data stored in continuous memory.
void	fiftyoneDegreesDataSetReset (fiftyoneDegreesDataSetBase *dataSet)
	Resets a newly allocated data set structure ready for initialisation.
fiftyoneDegreesDataSetBase *	fiftyoneDegreesDataSetGet (fiftyoneDegreesResourceManager *manager)
	Gets a pointer to the active data set from a resource manager.
void	fiftyoneDegreesDataSetRelease (fiftyoneDegreesDataSetBase *dataSet)
	Releases a reference to a data set which has been fetched via the DataSetGet method.
void	fiftyoneDegreesDataSetFree (fiftyoneDegreesDataSetBase *dataSet)
	Closes the data set by freeing anything which has been initialised at creation.
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetReloadManagerFromMemory (fiftyoneDegreesResourceManager manager, void source, fiftyoneDegreesFileOffset length, size_t dataSetSize, fiftyoneDegreesDataSetInitFromMemoryMethod initDataSet, void(freeDataSet)(void ), fiftyoneDegreesException *exception)
	Reload the data set being used by the resource manager using a data file loaded into contiguous memory.
fiftyoneDegreesStatusCode	fiftyoneDegreesDataSetReloadManagerFromFile (fiftyoneDegreesResourceManager manager, const char fileName, size_t dataSetSize, fiftyoneDegreesDataSetInitFromFileMethod initDataSet, void(freeDataSet)(void ), fiftyoneDegreesException *exception)
	Reload the data set being used by the resource manager using the data file location specified.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_DATASET_RELOAD

#define FIFTYONE_DEGREES_DATASET_RELOAD

(

t

)

Reload functions are common across all data set implementations where the naming of the data set type and the init methods comform to the common pattern.

This macro requires the init methods to be static and of the form initDataFrom[Memory|File]. The data set name must be DataSet[Type].

Parameters

t	the name of the resource type to define reload methods for

Typedef Documentation

◆ fiftyoneDegreesDataSetInitFromFileMethod

typedef fiftyoneDegreesStatusCode(* fiftyoneDegreesDataSetInitFromFileMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)

Initialses the data set from data stored on file.

This method should clean up the resource properly if the initialisation process fails. That means all allocated memory should be freed and pointers to these memorys should be set to NULL. The input dataSet should also be freed.

Parameters

dataSet	pointer to the data set to be initialised
config	configuration for the operation of the data set, or NULL if default configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the hash data file should be available for consumption
fileName	the full path to a file with read permission that contains the data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns: the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitFromMemoryMethod

typedef fiftyoneDegreesStatusCode(* fiftyoneDegreesDataSetInitFromMemoryMethod) (void *dataSet, const void *config, fiftyoneDegreesPropertiesRequired *properties, void *memory, fiftyoneDegreesFileOffset size, fiftyoneDegreesException *exception)

Initialses the data set from data stored in continuous memory.

Parameters

dataSet	pointer to the data set to be initialised
config	configuration for the operation of the data set, or NULL if default configuration is required
properties	the properties that will be consumed from the data set, or NULL if all available properties in the hash data file should be available for consumption
memory	pointer to continuous memory containing the data set
size	the number of bytes that make up the data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

Function Documentation

◆ fiftyoneDegreesDataSetFree()

void fiftyoneDegreesDataSetFree

(

fiftyoneDegreesDataSetBase *

dataSet

)

Closes the data set by freeing anything which has been initialised at creation.

This does not free the data set structure itself.

Parameters

dataSet pointer to the data set to complete

◆ fiftyoneDegreesDataSetGet()

fiftyoneDegreesDataSetBase * fiftyoneDegreesDataSetGet

(

fiftyoneDegreesResourceManager *

manager

)

Gets a pointer to the active data set from a resource manager.

Note that when this is finished with it must be released with the corresponding release method.

Parameters

manager pointer to the manager which manages the data set resource

Returns: pointer to the data set resource

◆ fiftyoneDegreesDataSetInitFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitFromFile	(	fiftyoneDegreesDataSetBase *	dataSet,
		const char *	fileName,
		fiftyoneDegreesFileOffset	bytesToCompare )

Initialses the data set from data stored on file.

Parameters

dataSet	pointer to the pre allocated data set to be initialised
fileName	the full path to a file with read permission that contains the data set
bytesToCompare	the number of bytes to compare if the reuse temporary file option is enabled. If a temporary file is found and the first bytes are equal to the master file, then the file is used, if not then a new temporary file is created

Returns: the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitHeaders()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitHeaders	(	fiftyoneDegreesDataSetBase *	dataSet,
		void *	state,
		fiftyoneDegreesHeadersGetMethod	getHeaderMethod,
		fiftyoneDegreesException *	exception )

Initialises the HTTP headers in the data set.

Usually this means constructing an array of pointers to the headers which are required for quick access.

Parameters

dataSet	pointer to a valid data set
state	pointer to data which is needed by getPropertymethod
getHeaderMethod	method used to retrieve the unique id and name of a header at a specified index from the data set
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: the status associated with the header initialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the headers were not initialised correctly

◆ fiftyoneDegreesDataSetInitInMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitInMemory	(	fiftyoneDegreesDataSetBase *	dataSet,
		fiftyoneDegreesMemoryReader *	reader )

Initialses the data set from data stored in continuous memory.

Parameters

dataSet	pointer to the pre allocated data set to be initialised
reader	constructed to read the memory containing the data set

Returns: the status associated with the data set intialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not initialised correctly

◆ fiftyoneDegreesDataSetInitProperties()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetInitProperties	(	fiftyoneDegreesDataSetBase *	dataSet,
		fiftyoneDegreesPropertiesRequired *	properties,
		void *	state,
		fiftyoneDegreesPropertiesGetMethod	getPropertyMethod,
		fiftyoneDegreesEvidencePropertiesGetMethod	getEvidencePropertiesMethod )

Initialises the properties in the data set.

Usually this means constructing an array of pointers to the properties which are required for quick access.

Parameters

dataSet	pointer to a valid data set
properties	the properties which should be initialised in the data set
state	pointer to data which is needed by getPropertymethod
getPropertyMethod	method used to retrieve the name of a property at a specified index from the data set
getEvidencePropertiesMethod	method used to populate the list of evidence required for a property in the data set

Returns: the status associated with the property initialisation. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the properties were not initialised correctly

◆ fiftyoneDegreesDataSetRelease()

void fiftyoneDegreesDataSetRelease

(

fiftyoneDegreesDataSetBase *

dataSet

)

Releases a reference to a data set which has been fetched via the DataSetGet method.

Parameters

dataSet pointer to the data set to release

◆ fiftyoneDegreesDataSetReloadManagerFromFile()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetReloadManagerFromFile	(	fiftyoneDegreesResourceManager *	manager,
		const char *	fileName,
		size_t	dataSetSize,
		fiftyoneDegreesDataSetInitFromFileMethod	initDataSet,
		void(*	freeDataSet )(void *),
		fiftyoneDegreesException *	exception )

Reload the data set being used by the resource manager using the data file location specified.

When initialising the data, the configuration that manager was first created with is used.

If the new data file is successfully initialised, the current data set is replaced The old data will remain in memory until the last reference to it is released.

Parameters

manager	pointer to the resource manager to reload the data set for
fileName	path to the new data file
dataSetSize	size of the data set structure to allocate for the new data set
initDataSet	init method used to initialise the new data set from the file provided
freeDataSet	the engine's free method, called on the replacement data set if initialisation fails so a failed reload does not leak. Must be safe on a partially initialised data set, which every engine's free method is because its init method resets the pointers first
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded and the current one stays in use

◆ fiftyoneDegreesDataSetReloadManagerFromMemory()

fiftyoneDegreesStatusCode fiftyoneDegreesDataSetReloadManagerFromMemory	(	fiftyoneDegreesResourceManager *	manager,
		void *	source,
		fiftyoneDegreesFileOffset	length,
		size_t	dataSetSize,
		fiftyoneDegreesDataSetInitFromMemoryMethod	initDataSet,
		void(*	freeDataSet )(void *),
		fiftyoneDegreesException *	exception )

Reload the data set being used by the resource manager using a data file loaded into contiguous memory.

When initialising the data, the configuration that manager was first created with is used.

If the data passed in is successfully initialised, the current data set is replaced The old data will remain in memory until the last reference to it is released.

Parameters

manager	pointer to the resource manager to reload the data set for
source	pointer to the memory location where the new data file is stored
length	of the data in memory
dataSetSize	size of the data set structure to allocate for the new data set
initDataSet	init method used to initialise the new data set from the memory pointer provided
freeDataSet	the engine's free method, called on the replacement data set if initialisation fails so a failed reload does not leak. Must be safe on a partially initialised data set, which every engine's free method is because its init method resets the pointers first
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: the status associated with the data set reload. Any value other than FIFTYONE_DEGREES_STATUS_SUCCESS means the data set was not reloaded and the current one stays in use

◆ fiftyoneDegreesDataSetReset()

void fiftyoneDegreesDataSetReset

(

fiftyoneDegreesDataSetBase *

dataSet

)

Resets a newly allocated data set structure ready for initialisation.

Parameters

dataSet pointer to the allocated data set

Data Set Common

Detailed Description

Terms

Introduction

Creation

Operation

Reloading

Free

Collaboration diagram for Data Set:

Structs

Macros

Typedefs

Functions

Macro Definition Documentation

◆ FIFTYONE_DEGREES_DATASET_RELOAD

Typedef Documentation

◆ fiftyoneDegreesDataSetInitFromFileMethod

◆ fiftyoneDegreesDataSetInitFromMemoryMethod

Function Documentation

◆ fiftyoneDegreesDataSetFree()

◆ fiftyoneDegreesDataSetGet()

◆ fiftyoneDegreesDataSetInitFromFile()

◆ fiftyoneDegreesDataSetInitHeaders()

◆ fiftyoneDegreesDataSetInitInMemory()

◆ fiftyoneDegreesDataSetInitProperties()

◆ fiftyoneDegreesDataSetRelease()

◆ fiftyoneDegreesDataSetReloadManagerFromFile()

◆ fiftyoneDegreesDataSetReloadManagerFromMemory()

◆ fiftyoneDegreesDataSetReset()

Data Set
Common