◆ FIFTYONE_DEGREES_COLLECTION_FREE
#define FIFTYONE_DEGREES_COLLECTION_FREE | ( | c | ) | if (c != NULL) { c->freeCollection(c); } |
Free a collection by checking if it is NULL first.
- Parameters
-
- c - collection to free
◆ FIFTYONE_DEGREES_COLLECTION_RELEASE
#define FIFTYONE_DEGREES_COLLECTION_RELEASE ( c, i ) c->release(i) Collection release macro used to release a collection item.
This should always be used in place of the release method to enable methods to be optimised out at compile time when memory only mode is set.
- Parameters
-
- c - collection the item belongs to
- i - item to release
Typedef Documentation
◆ fiftyoneDegreesCollectionFileRead
typedef void*(* fiftyoneDegreesCollectionFileRead) (const fiftyoneDegreesCollectionFile *collection, uint32_t offsetOrIndex, fiftyoneDegreesData *data, fiftyoneDegreesException *exception) Reads the item from the underlying data file.
Used by the file related collection methods.
- Parameters
-
- collection - pointer to the file collection
- offsetOrIndex - index or offset to the item in the data structure
- data - pointer to the data structure to store the item
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- the value in the data->ptr field, or NULL if not successful
◆ fiftyoneDegreesCollectionFreeMethod
typedef void(* fiftyoneDegreesCollectionFreeMethod) (fiftyoneDegreesCollection *collection) Frees all the memory and handles associated with the collection.
- Parameters
-
- collection - the collection to be freed
◆ fiftyoneDegreesCollectionGetFileVariableSizeMethod
typedef uint32_t(* fiftyoneDegreesCollectionGetFileVariableSizeMethod) (void *initial) Passed a pointer to the first part of a variable size item and returns the size of the entire item.
- Parameters
-
- initial - pointer to the start of the item
- Returns
- size of the item in bytes
◆ fiftyoneDegreesCollectionGetMethod
typedef void*(* fiftyoneDegreesCollectionGetMethod) (fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception) Gets an item from the collection.
Returns a pointer to the item, or NULL if the item could not be loaded. The exception parameter is set to the status code to indicate the failure.
- Parameters
-
- collection - pointer to the file collection
- offsetOrIndex - index or offset to the item in the data structure
- item - pointer to the item structure to place the result in
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- the value in the data->ptr field, or NULL if not successful
◆ fiftyoneDegreesCollectionItemComparer
typedef int(* fiftyoneDegreesCollectionItemComparer) (void *state, fiftyoneDegreesCollectionItem *item, long curIndex, fiftyoneDegreesException *exception) Compares two items and returns the difference between them for the purposes of a binary search of ordering operation.
- Parameters
-
- state - to be used for the comparison
- item - the value to compare against the state
- curIndex - the index of the current item in the collection
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h
- Returns
- negative if a is lower than b, positive if a is higher than b or 0 if equal.
◆ fiftyoneDegreesCollectionIterateMethod
typedef bool(* fiftyoneDegreesCollectionIterateMethod) (void *state, uint32_t key, void *data) Method used to iterate over data held in a collection.
- Parameters
-
- state - state data for all callbacks
- key - the key used with get method of the item being returned
- data - data for the specific item
- Returns
- true if the iteration should continue, otherwise false to stop it
◆ fiftyoneDegreesCollectionReleaseMethod
typedef void(* fiftyoneDegreesCollectionReleaseMethod) (fiftyoneDegreesCollectionItem *item) Releases the item so that the collection can free the memory or take other actions when the caller no longer needs access to the item.
- Parameters
-
- item - the item returned from Get to be released
Function Documentation
◆ fiftyoneDegreesCollectionBinarySearch()
long fiftyoneDegreesCollectionBinarySearch ( fiftyoneDegreesCollection * collection, fiftyoneDegreesCollectionItem * item, uint32_t lowerIndex, uint32_t upperIndex, void * state, fiftyoneDegreesCollectionItemComparer comparer, fiftyoneDegreesException * exception ) Where a collection is fixed width and contains an ordered list of items this method is used to perform a divide and conquer search.
The state and the comparer are used to compare the current index with the value being sought. If an item is found in the collection the item parameter will contain that item when the method completes. The caller will therefore need to release the item when it's finished with it.
- Parameters
-
- collection - to be searched
- item - memory to be used to store the current value being compared. Will have a lock on the item at the index returned if an item is found. The caller should release the item when finished with it.
- lowerIndex - to start the search at
- upperIndex - to end the search at
- state - used with the compare method when comparing items
- comparer - method used to perform the comparison
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- the index of the item if found, otherwise -1.
◆ fiftyoneDegreesCollectionCreateFromFile()
fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromFile ( FILE * file, fiftyoneDegreesFilePool * reader, const fiftyoneDegreesCollectionConfig * config, fiftyoneDegreesCollectionHeader header, fiftyoneDegreesCollectionFileRead read ) Creates a collection from the file handle at the current position in the file.
The first 4 bytes read will be the number if fixed with items in the collection OR the number of bytes until the end of the collection data.
- Parameters
-
- file - a file handle positioned at the start of the collection
- reader - a pool of file handles to use operationally to retrieve data from the file after the collection has been created. These are often shared across different collections accessing the same data file.
- config - settings for the implementation of the collection to be used. If FIFTYONE_DEGREES_MEMORY_ONLY is defined, then this is either NULL or it is ignored
- header - containing collection structure
- read - a pointer to a function to read an item into the collection
- Returns
- pointer to the new collection, or NULL if something went wrong
◆ fiftyoneDegreesCollectionCreateFromMemory()
fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromMemory ( fiftyoneDegreesMemoryReader * reader, fiftyoneDegreesCollectionHeader header ) Creates the collection from a memory reader where the collection maps to the memory allocated to the reader.
The resulting collection does not free the memory used to store the data. This method is used where the entire data structure is loaded into continuous memory and provides a high performance collection in all threading situations.
- Parameters
-
- reader - with access to the allocated memory
- header - containing collection structure
- Returns
- pointer to the memory collection, or NULL if the collection could not be created
◆ fiftyoneDegreesCollectionGetCount()
uint32_t fiftyoneDegreesCollectionGetCount ( fiftyoneDegreesCollection * collection ) Gets the actual number of items in the collection by iterating through to the base collection.
In cases where there are chained collections which pre-load and/or cache elements, the first collections may not contain the full collection of elements. Therefore the value of collection->count may not be correct. This method follows the collection->next pointers to get to the base collection containing the true count.
It is important to note that this gets the count for a collection of fixed size elements, and does not apply to collections of variable sized elements.
- Parameters
-
- collection - to get the count for
- Returns
- the number of items in the collection
◆ fiftyoneDegreesCollectionGetInteger32()
int32_t fiftyoneDegreesCollectionGetInteger32 ( fiftyoneDegreesCollection * collection, uint32_t indexOrOffset, fiftyoneDegreesException * exception ) Returns a 32 bit integer from collections that provide such values.
- Parameters
-
- collection - the collection of 32 bit integers
- indexOrOffset - the index or offset of the integer required
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- the 32 bit integer at the index or offset provided
◆ fiftyoneDegreesCollectionGetIsMemoryOnly()
bool fiftyoneDegreesCollectionGetIsMemoryOnly ( ) Determines if in memory collection methods have been compiled so they are fully optimized.
This results in the loss of file stream operation. In memory only operation compiling without stream capabilities using the
FIFTYONE_DEGREES_MEMORY_ONLY
directive results in performance improvements.- Returns
- true if the library is compiled for memory only operation, otherwise false.
◆ fiftyoneDegreesCollectionHeaderFromFile()
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromFile ( FILE * file, uint32_t elementSize, bool isCount ) Reads the 4 bytes at the current reader position and configures the collection header.
The 4 bytes can either represent the number of fixed width items in the collection OR the number of bytes that follow the 4 bytes which form the collection. The caller must know the type of structure expected and set the elementSize and isCount parameters.
- Parameters
-
- file - a file handle positioned at the start of the collection
- elementSize - if known the size in bytes of each item, or 0 for variable width items
- isCount - the number of items in the collection if known
- Returns
- a header set with the details for the collection
◆ fiftyoneDegreesCollectionHeaderFromMemory()
fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromMemory ( fiftyoneDegreesMemoryReader * reader, uint32_t elementSize, bool isCount ) Reads the 4 bytes at the current reader position and configures the collection header.
The 4 bytes can either represent the number of fixed width items in the collection OR the number of bytes that follow the 4 bytes which form the collection. The caller must know the type of structure expected and set the elementSize and isCount parameters.
- Parameters
-
- reader - with access to the allocated memory
- elementSize - if known the size in bytes of each item, or 0 for variable width items
- isCount - the number of items in the collection if known
- Returns
- a header set with the details for the collection
◆ fiftyoneDegreesCollectionReadFileFixed()
void* fiftyoneDegreesCollectionReadFileFixed ( const fiftyoneDegreesCollectionFile * file, uint32_t index, fiftyoneDegreesData * data, fiftyoneDegreesException * exception ) Used with collections where each item is a fixed number of bytes recorded in elementSize.
The method will read that number of bytes into the data item ensuring sufficient memory is allocated. Contained in the collection to avoid repeating this common method across different collection consumers.
- Parameters
-
- file - pointer to the fiftyoneDegreesCollectionFile to use for the read
- data - structure to populate with a reference to the item
- index - zero based index of the item required in the fixed with data structure
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- a pointer to the item in the data structure or NULL if can't be found due to an invalid index
◆ fiftyoneDegreesCollectionReadFilePosition()
fiftyoneDegreesFileHandle* fiftyoneDegreesCollectionReadFilePosition ( const fiftyoneDegreesCollectionFile * file, uint32_t offset, fiftyoneDegreesException * exception ) Get a handle from the file pool associated with the collection and position the file handle at the offset provided.
- Parameters
-
- file - pointer to the fiftyoneDegreesCollectionFile to use for the read
- offset - from the start of the data structure, not the entire file, where the item should be read from
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- a file handle for further read operations, or NULL if the offset is invalid, or a handle can not be obtained.
◆ fiftyoneDegreesCollectionReadFileVariable()
void* fiftyoneDegreesCollectionReadFileVariable ( const fiftyoneDegreesCollectionFile * file, fiftyoneDegreesData * data, uint32_t offset, void * initial, size_t initialSize, fiftyoneDegreesCollectionGetFileVariableSizeMethod getFinalSize, fiftyoneDegreesException * exception ) Reads a variable size item from the file where the initial bytes can be used to calculate the size of the entire item.
- Parameters
-
- file - pointer to the fiftyoneDegreesCollectionFile to use for the read
- data - structure to populate with a reference to the item
- offset - zero based offset to the item within the data structure
- initial - pointer to enough memory to store the initial data
- initialSize - amount of initial data to read
- getFinalSize - method pass the initial pointer to get the final size
- exception - pointer to an exception data structure to be used if an exception occurs. See exceptions.h.
- Returns
- a pointer to the item in the data structure or NULL if can't be found due to an invalid index