diff options
Diffstat (limited to 'src/cc4group.h')
| -rw-r--r-- | src/cc4group.h | 24 |
1 files changed, 20 insertions, 4 deletions
diff --git a/src/cc4group.h b/src/cc4group.h index 2309338..c8ff6f6 100644 --- a/src/cc4group.h +++ b/src/cc4group.h @@ -29,7 +29,7 @@ // the directory separator used for all entry paths in cc4group is "/" _regardless of the platform_. yes, you better watch out Windows users! // in contrast to paths names are only the the name of the entry itself, not the whole path // - to free all resources used by the group when it is not needed anymore, call cc4group.delete with the group pointer and discard it afterwards (i.e. don't use it anymore) -// - all functions, except cc4group.new, cc4group.openAsChild, cc4group.delete and cc4group.setTmpMemoryStrategy (where the latter two can't fail) follow the same scheme +// - all functions, except cc4group.new, cc4group.setLazy, cc4group.openAsChild, cc4group.delete and cc4group.setTmpMemoryStrategy (where the latter two can't fail) follow the same scheme // all of them can fail, either caused by wrong arguments or by things outside of the applications control // they all return _true_ if everything went well and _false_ if any error occured // information about the error (incredibly useful for debugging or asking for help with problems) can be obtained by using one the cc4group.getError* functions @@ -142,6 +142,8 @@ typedef void* (*CC4Group_TmpMemoryStrategy)(CC4Group* const this, const size_t s // and of an end function, which does the actual cleanup // and an optional custom arg that will be passed to both functions // additionally to the predefined memory management strategies, custom strategies may be used +// the start and end functions must have well-defined behavior when data = NULL and size = 0 (at the same time) +// as this is used to signal the start and end of a prolonged use of the memory management strategy (needed for reference counting in cppc4group's custom memory management implementation) typedef struct { void* (*start)(void* const data, const size_t size, void* const arg); void (*end)(void* const data, void* const arg); @@ -213,6 +215,12 @@ typedef struct { // child relations are tracked through reference counting, thus the group will be really destructed when all referencing child groups are gone void (*delete)(CC4Group* const this); + // de-/activates the group's lazy mode + // in lazy mode, only as much data is read and uncompressed as needed by the latest call that needs some data + // by default the lazy mode is activated + // if you know that the whole group needs to be read anyway (e.g. for saving it later) it's a little bit faster in the end to disable the lazy mode + // if only a few data are needed from the group, the lazy mode may be significantly faster, depending on where the data is actually positioned in the group + void (*setLazy)(CC4Group* const this, const bool lazy); // after creating a group with new, exactly one of create, openExisting, openMemory, openFd, openFilePointer or openWithReadCallback must be called before any other action on the group object may be executed (except delete) // initializes the group to be a fresh, empty group @@ -224,7 +232,7 @@ typedef struct { // opens a group that is stored entirely in memory // see the description of MemoryManagement to know if and when data has to be freed by the caller // if the lazy mode is not used, the data can be freed immediately after this function returns - // HINT: the lazy mode is actually not implemented yet, but at least I can't forget to mention it here anymore when it's actually done + // but if the lazy mode is used, the data can only be freed after the whole group has been read, or the cc4group object is deleted bool (*openMemory)(CC4Group* const this, const void* const groupData, size_t const size, CC4Group_MemoryManagement const memoryManagement); // opens a group through a file descriptor @@ -240,6 +248,7 @@ typedef struct { // initCallback is called before readCallback is called and deinitCallback is called after all read operations are done // initCallback and deinitCallback may be NULL if they should not be used // even when using the Reference memory management, the buffer returned by the readCallback may be reused across callback calls + // be careful, if the lazy mode is activated, all pointer arguments (most importantly callbackArg) passed in here needs to stay valid until the group object is deleted or the whole group has been read bool (*openWithReadCallback)(CC4Group* const this, CC4Group_ReadCallback const readCallback, void* const callbackArg, CC4Group_MemoryManagement const memoryManagement, CC4Group_ReadSetupCallback const initCallback, CC4Group_ReadSetupCallback const deinitCallback); @@ -283,14 +292,21 @@ typedef struct { // retrieval of metadata about the stored files and directories // stores all metadata known about the entry denoted by path into the CC4Group_EntryInfo struct pointed to by info, similar to stat // an empty path "" or NULL will retrieve information about the root directory - bool (*getEntryInfo)(CC4Group* const this, const char* const path, CC4Group_EntryInfo* const info); + // even if the group's lazy mode is activated, when getting the entry info of a directory, the directories group header must be loaded, which may be far inside the group... + // ..and requires to load everything up to that point, which may be quite slow + // if lazy is specified as true and the group's lazy mode is enabled, only information available from the parent group's header... + // ...and the entry's core will be used to fill out the entry info... + // ...this means that the following info may be inaccurate: modified, author, size, official + // if lazy is specified as false or the group has been loaded eagerly (i.e. not lazy), accurate information will be returned instead + bool (*getEntryInfo)(CC4Group* const this, const char* const path, CC4Group_EntryInfo* const info, bool const lazy); // retrieves all metadata like getEntryInfo of all files and directories inside the directory denoted by path, similar to ls // a pointer to a dynamically allocated array of all CC4Group_EntryInfo structs will be stored in infos // the amount of infos (and thus the amount of files in the directory) is stored in size // the caller must free the pointer stored in infos when it is not needed anymore // an empty path "" or NULL will retrieve information about the root directory - bool (*getEntryInfos)(CC4Group* const this, const char* const path, CC4Group_EntryInfo** const infos, size_t* const size); + // the lazy argument is the same as in getEntryInfo above + bool (*getEntryInfos)(CC4Group* const this, const char* const path, CC4Group_EntryInfo** const infos, size_t* const size, bool const lazy); // data retrieval and manipulation |