51Degrees Common C/C++  4.1

A shared functionality library that is used by 51Degrees products
Search

collection.h

1 /* *********************************************************************
2  * This Source Code Form is copyright of 51 Degrees Mobile Experts Limited.
3  * Copyright 2019 51 Degrees Mobile Experts Limited, 5 Charlotte Close,
4  * Caversham, Reading, Berkshire, United Kingdom RG4 7BY
5  *
6  * This Source Code Form is subject to the terms of the Mozilla Public
7  * License, v. 2.0.
8  *
9  * If a copy of the MPL was not distributed with this file, You can obtain
10  * one at http://mozilla.org/MPL/2.0/.
11  *
12  * This Source Code Form is "Incompatible With Secondary Licenses", as
13  * defined by the Mozilla Public License, v. 2.0.
14  * ********************************************************************* */
15 
16 #ifndef FIFTYONE_DEGREES_COLLECTION_H_INCLUDED
17 #define FIFTYONE_DEGREES_COLLECTION_H_INCLUDED
18 
229  /* Define NDEBUG if needed, to ensure asserts are disabled in release builds */
230 #if !defined(DEBUG) && !defined(_DEBUG) && !defined(NDEBUG)
231 #define NDEBUG
232 #endif
233 
234 #include "data.h"
235 #include "exceptions.h"
236 #include "cache.h"
237 #include "file.h"
238 #include "memory.h"
239 #include <stdio.h>
240 #include <string.h>
241 #include <assert.h>
242 
247 #define FIFTYONE_DEGREES_COLLECTION_FREE(c) \
248 if (c != NULL) { c->freeCollection(c); }
249 
250 
258 #ifndef FIFTYONE_DEGREES_MEMORY_ONLY
259 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i) c->release(i)
260 #else
261 #define FIFTYONE_DEGREES_COLLECTION_RELEASE(c, i)
262 #endif
263 
264 
269 #pragma pack(push, 4)
270 typedef struct fiftyone_degrees_collection_header_t {
271  uint32_t startPosition;
272  uint32_t length;
273  uint32_t count;
274 } fiftyoneDegreesCollectionHeader;
275 #pragma pack(pop)
276 
281 typedef struct fiftyone_degrees_collection_config_t {
282  uint32_t loaded;
284  uint32_t capacity;
286  uint16_t concurrency;
288 } fiftyoneDegreesCollectionConfig;
289 
291 typedef struct fiftyone_degrees_collection_t fiftyoneDegreesCollection;
292 typedef struct fiftyone_degrees_collection_item_t fiftyoneDegreesCollectionItem;
293 typedef struct fiftyone_degrees_collection_file_t fiftyoneDegreesCollectionFile;
302 typedef struct fiftyone_degrees_collection_item_t {
303  fiftyoneDegreesData data;
304  void *handle;
305  fiftyoneDegreesCollection *collection;
309 } fiftyoneDegreesCollectionItem;
310 
322 typedef void* (*fiftyoneDegreesCollectionGetMethod)(
323  fiftyoneDegreesCollection *collection,
324  uint32_t indexOrOffset,
325  fiftyoneDegreesCollectionItem *item,
326  fiftyoneDegreesException *exception);
327 
334 typedef uint32_t (*fiftyoneDegreesCollectionGetFileVariableSizeMethod)(
335  void *initial);
336 
347 typedef void* (*fiftyoneDegreesCollectionFileRead)(
348  const fiftyoneDegreesCollectionFile *collection,
349  uint32_t offsetOrIndex,
350  fiftyoneDegreesData *data,
351  fiftyoneDegreesException *exception);
352 
363 typedef int(*fiftyoneDegreesCollectionItemComparer)(
364  void *state,
365  fiftyoneDegreesCollectionItem *item,
366  fiftyoneDegreesException *exception);
367 
373 typedef void (*fiftyoneDegreesCollectionReleaseMethod)(
374  fiftyoneDegreesCollectionItem* item);
375 
380 typedef void(*fiftyoneDegreesCollectionFreeMethod)(
381  fiftyoneDegreesCollection* collection);
382 
390 typedef bool(*fiftyoneDegreesCollectionIterateMethod)(
391  void *state,
392  uint32_t key,
393  void *data);
394 
400 typedef struct fiftyone_degrees_collection_t {
401  fiftyoneDegreesCollectionGetMethod get;
405  fiftyoneDegreesCollectionReleaseMethod release;
407  fiftyoneDegreesCollectionFreeMethod freeCollection;
411  void *state;
415  fiftyoneDegreesCollection *next;
417  uint32_t count;
418  uint32_t elementSize;
419  uint32_t size;
421 } fiftyoneDegreesCollection;
422 
426 typedef struct fiftyone_degrees_collection_memory_t {
427  fiftyoneDegreesCollection *collection;
428  byte *firstByte;
429  byte *lastByte;
430  void *memoryToFree;
432 } fiftyoneDegreesCollectionMemory;
433 
437 typedef struct fiftyone_degrees_collection_file_t {
438  fiftyoneDegreesCollection *collection;
439  fiftyoneDegreesFilePool *reader;
441  long offset;
442  fiftyoneDegreesCollectionFileRead read;
445 } fiftyoneDegreesCollectionFile;
446 
452 typedef struct fiftyone_degrees_collection_cache_t {
453  fiftyoneDegreesCollection *source;
455  fiftyoneDegreesCache *cache;
456 } fiftyoneDegreesCollectionCache;
457 
466 EXTERNAL bool fiftyoneDegreesCollectionGetIsMemoryOnly();
467 
476 EXTERNAL int32_t fiftyoneDegreesCollectionGetInteger32(
477  fiftyoneDegreesCollection *collection,
478  uint32_t indexOrOffset,
479  fiftyoneDegreesException *exception);
480 
496 EXTERNAL fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromFile(
497  FILE *file,
498  fiftyoneDegreesFilePool *reader,
499  const fiftyoneDegreesCollectionConfig *config,
500  fiftyoneDegreesCollectionHeader header,
501  fiftyoneDegreesCollectionFileRead read);
502 
514 EXTERNAL fiftyoneDegreesCollection* fiftyoneDegreesCollectionCreateFromMemory(
515  fiftyoneDegreesMemoryReader *reader,
516  fiftyoneDegreesCollectionHeader header);
517 
529 EXTERNAL fiftyoneDegreesFileHandle* fiftyoneDegreesCollectionReadFilePosition(
530  const fiftyoneDegreesCollectionFile *file,
531  uint32_t offset,
532  fiftyoneDegreesException *exception);
533 
550 EXTERNAL void* fiftyoneDegreesCollectionReadFileFixed(
551  const fiftyoneDegreesCollectionFile *file,
552  uint32_t index,
553  fiftyoneDegreesData *data,
554  fiftyoneDegreesException *exception);
555 
568 EXTERNAL fiftyoneDegreesCollectionHeader
569 fiftyoneDegreesCollectionHeaderFromFile(
570  FILE *file,
571  uint32_t elementSize,
572  bool isCount);
573 
589 EXTERNAL void* fiftyoneDegreesCollectionReadFileVariable(
590  const fiftyoneDegreesCollectionFile *file,
591  fiftyoneDegreesData *data,
592  uint32_t offset,
593  void *initial,
594  size_t initialSize,
595  fiftyoneDegreesCollectionGetFileVariableSizeMethod getFinalSize,
596  fiftyoneDegreesException *exception);
597 
610 EXTERNAL fiftyoneDegreesCollectionHeader
611 fiftyoneDegreesCollectionHeaderFromMemory(
612  fiftyoneDegreesMemoryReader *reader,
613  uint32_t elementSize,
614  bool isCount);
615 
616 
636 EXTERNAL long fiftyoneDegreesCollectionBinarySearch(
637  fiftyoneDegreesCollection *collection,
638  fiftyoneDegreesCollectionItem *item,
639  uint32_t lowerIndex,
640  uint32_t upperIndex,
641  void *state,
642  fiftyoneDegreesCollectionItemComparer comparer,
643  fiftyoneDegreesException *exception);
644 
658 EXTERNAL uint32_t fiftyoneDegreesCollectionGetCount(
659  fiftyoneDegreesCollection *collection);
660 
665 #endif
fiftyoneDegreesCollectionReadFileVariable
EXTERNAL 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...
Definition: collection.c:1089
fiftyoneDegreesCollectionCache::source
fiftyoneDegreesCollection * source
The source collection used to load items into the cache.
Definition: collection.h:453
fiftyoneDegreesCollectionCache
Type of collection where items are cached as they are used.
Definition: collection.h:452
fiftyoneDegreesCollectionFile::read
fiftyoneDegreesCollectionFileRead read
Read method used to read an item from file at an offset or index.
Definition: collection.h:442
fiftyoneDegreesCollectionHeader
Collection header structure which defines the size and location of the collection data.
Definition: collection.h:270
fiftyoneDegreesCollectionCache::cache
fiftyoneDegreesCache * cache
Loading cache to use as data source.
Definition: collection.h:455
fiftyoneDegreesCollectionItemComparer
int(* fiftyoneDegreesCollectionItemComparer)(void *state, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
Compares two items and returns the difference between them for the purposes of a binary search of ord...
Definition: collection.h:363
fiftyoneDegreesCollectionCreateFromMemory
EXTERNAL fiftyoneDegreesCollection * fiftyoneDegreesCollectionCreateFromMemory(fiftyoneDegreesMemoryReader *reader, fiftyoneDegreesCollectionHeader header)
Creates the collection from a memory reader where the collection maps to the memory allocated to the ...
Definition: collection.c:755
fiftyoneDegreesCollectionFile::collection
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:438
fiftyoneDegreesCollectionGetIsMemoryOnly
EXTERNAL bool fiftyoneDegreesCollectionGetIsMemoryOnly()
Determines if in memory collection methods have been compiled so they are fully optimized.
Definition: collection.c:63
fiftyoneDegreesCollectionIterateMethod
bool(* fiftyoneDegreesCollectionIterateMethod)(void *state, uint32_t key, void *data)
Method used to iterate over data held in a collection.
Definition: collection.h:390
fiftyoneDegreesCollectionItem
Used to store a handle to the underlying item that could be used to release the item when it's finish...
Definition: collection.h:302
fiftyoneDegreesCollectionReleaseMethod
void(* fiftyoneDegreesCollectionReleaseMethod)(fiftyoneDegreesCollectionItem *item)
Releases the item so that the collection can free the memory or take other actions when the caller no...
Definition: collection.h:373
fiftyoneDegreesMemoryReader
Used to read data from memory in a similar manner to a file handle.
Definition: memory.h:51
fiftyoneDegreesCollectionFileRead
void *(* fiftyoneDegreesCollectionFileRead)(const fiftyoneDegreesCollectionFile *collection, uint32_t offsetOrIndex, fiftyoneDegreesData *data, fiftyoneDegreesException *exception)
Reads the item from the underlying data file.
Definition: collection.h:347
fiftyoneDegreesCache
Cache structure to store the root of the red black tree and a list of allocated cache nodes.
Definition: cache.h:177
fiftyoneDegreesCollection::freeCollection
fiftyoneDegreesCollectionFreeMethod freeCollection
Frees collection and all items retrieved from the collection will become invalid.
Definition: collection.h:407
fiftyoneDegreesCollectionGetMethod
void *(* fiftyoneDegreesCollectionGetMethod)(fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesCollectionItem *item, fiftyoneDegreesException *exception)
Gets an item from the collection.
Definition: collection.h:322
fiftyoneDegreesCollection::count
uint32_t count
The number of items, or 0 if not available.
Definition: collection.h:417
fiftyoneDegreesCollectionFile
Type of collection where the collection is streamed from file.
Definition: collection.h:437
fiftyoneDegreesCollectionItem::collection
fiftyoneDegreesCollection * collection
Collection the item came from which may not have been set.
Definition: collection.h:305
fiftyoneDegreesCollectionConfig::capacity
uint32_t capacity
Number of items the cache should store, 0 for no cache.
Definition: collection.h:284
fiftyoneDegreesCollectionMemory::firstByte
byte * firstByte
The first byte in memory of the collection.
Definition: collection.h:428
fiftyoneDegreesData
Data structure used for reusing memory which may have been allocated in a previous operation.
Definition: data.h:99
fiftyoneDegreesCollectionHeader::count
uint32_t count
Number of entities in the collection.
Definition: collection.h:273
fiftyoneDegreesCollectionReadFilePosition
EXTERNAL 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 of...
Definition: collection.c:926
fiftyoneDegreesCollectionItem::handle
void * handle
A handle that relates to the data.
Definition: collection.h:304
fiftyoneDegreesCollectionHeader::startPosition
uint32_t startPosition
Start position in the data file of the entities.
Definition: collection.h:271
fiftyoneDegreesCollectionFile::offset
long offset
Offset to the collection in the source data structure.
Definition: collection.h:441
fiftyoneDegreesCollectionMemory::memoryToFree
void * memoryToFree
Memory to free when freeing the collection, or NULL if no memory to free.
Definition: collection.h:430
fiftyoneDegreesCollection::next
fiftyoneDegreesCollection * next
The next collection implementation or NULL.
Definition: collection.h:415
fiftyoneDegreesCollectionFile::reader
fiftyoneDegreesFilePool * reader
Reader used to load items into the cache, or NULL if no cache.
Definition: collection.h:439
fiftyoneDegreesCollectionGetInteger32
EXTERNAL int32_t fiftyoneDegreesCollectionGetInteger32(fiftyoneDegreesCollection *collection, uint32_t indexOrOffset, fiftyoneDegreesException *exception)
Returns a 32 bit integer from collections that provide such values.
Definition: collection.c:1137
fiftyoneDegreesCollectionConfig::concurrency
uint16_t concurrency
Expected number of concurrent requests, 1 or greater.
Definition: collection.h:286
fiftyoneDegreesCollectionGetCount
EXTERNAL uint32_t fiftyoneDegreesCollectionGetCount(fiftyoneDegreesCollection *collection)
Gets the actual number of items in the collection by iterating through to the base collection.
Definition: collection.c:1199
fiftyoneDegreesFileHandle
File handle node in the stack of handles.
Definition: file.h:207
fiftyoneDegreesCollection::elementSize
uint32_t elementSize
The size of each entry, or 0 if variable length.
Definition: collection.h:418
fiftyoneDegreesCollection::get
fiftyoneDegreesCollectionGetMethod get
Gets an entry into the item provided.
Definition: collection.h:401
fiftyoneDegreesCollection::state
void * state
Pointer to data for memory, cache or file.
Definition: collection.h:411
fiftyoneDegreesCollectionConfig::loaded
uint32_t loaded
Number of items to load into memory from the start of the collection.
Definition: collection.h:282
fiftyoneDegreesCollectionConfig
Collection configuration structure which defines how the collection should be created by the create m...
Definition: collection.h:281
fiftyoneDegreesCollectionCreateFromFile
EXTERNAL 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.
Definition: collection.c:834
fiftyoneDegreesCollectionFreeMethod
void(* fiftyoneDegreesCollectionFreeMethod)(fiftyoneDegreesCollection *collection)
Frees all the memory and handles associated with the collection.
Definition: collection.h:380
fiftyoneDegreesException
Structure used to represent a 51Degrees exception and passed into methods that might generate excepti...
Definition: exceptions.h:109
fiftyoneDegreesCollectionHeaderFromMemory
EXTERNAL fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromMemory(fiftyoneDegreesMemoryReader *reader, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
Definition: collection.c:728
fiftyoneDegreesCollectionMemory
Type of collection where the collection is held in continuous memory.
Definition: collection.h:426
fiftyoneDegreesFilePool
Stack of handles used to read data from a single source file.
Definition: file.h:215
fiftyoneDegreesCollectionHeader::length
uint32_t length
Length in bytes of all the entities.
Definition: collection.h:272
fiftyoneDegreesCollection
All the shared methods and fields required by file, memory and cached collections.
Definition: collection.h:400
fiftyoneDegreesCollectionItem::data
fiftyoneDegreesData data
Item data including allocated memory.
Definition: collection.h:303
fiftyoneDegreesCollection::release
fiftyoneDegreesCollectionReleaseMethod release
Releases the item handle.
Definition: collection.h:405
fiftyoneDegreesCollectionHeaderFromFile
EXTERNAL fiftyoneDegreesCollectionHeader fiftyoneDegreesCollectionHeaderFromFile(FILE *file, uint32_t elementSize, bool isCount)
Reads the 4 bytes at the current reader position and configures the collection header.
Definition: collection.c:806
fiftyoneDegreesCollectionMemory::lastByte
byte * lastByte
The last byte in memory of the collection.
Definition: collection.h:429
fiftyoneDegreesCollectionBinarySearch
EXTERNAL 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 perfor...
Definition: collection.c:1151
fiftyoneDegreesCollectionMemory::collection
fiftyoneDegreesCollection * collection
The generic collection.
Definition: collection.h:427
fiftyoneDegreesCollection::size
uint32_t size
Number of bytes in the source data structure containing the collection's data.
Definition: collection.h:419
fiftyoneDegreesCollectionReadFileFixed
EXTERNAL 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.
Definition: collection.c:960
fiftyoneDegreesCollectionGetFileVariableSizeMethod
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.
Definition: collection.h:334

Generated by doxygen 1.8.15