/*****************************************************************************\ * Copyright (c) Athena Dev Teams - Licensed under GNU GPL * * For more information, see LICENCE in the main folder * * * *

Entry Reusage System

* * * * There are several root entry managers, each with a different entry size. * * Each manager will keep track of how many instances have been 'created'. * * They will only automatically destroy themselves after the last instance * * is destroyed. * * * * Entries can be allocated from the managers. * * If it has reusable entries (freed entry), it uses one. * * So no assumption should be made about the data of the entry. * * Entries should be freed in the manager they where allocated from. * * Failure to do so can lead to unexpected behaviours. * * * *

Advantages:

* * - The same manager is used for entries of the same size. * * So entries freed in one instance of the manager can be used by other * * instances of the manager. * * - Much less memory allocation/deallocation - program will be faster. * * - Avoids memory fragmentaion - program will run better for longer. * * * *

Disavantages:

* * - Unused entries are almost inevitable - memory being wasted. * * - A manager will only auto-destroy when all of its instances are * * destroyed so memory will usually only be recovered near the end. * * - Always wastes space for entries smaller than a pointer. * * * * WARNING: The system is not thread-safe at the moment. * * * * HISTORY: * * 0.1 - Initial version * * * * @version 0.1 - Initial version * * @author Flavio @ Amazon Project * * @encoding US-ASCII * * @see common#ers.c * \*****************************************************************************/ #ifndef _ERS_H_ #define _ERS_H_ #include "../common/cbasetypes.h" /*****************************************************************************\ * (1) All public parts of the Entry Reusage System. * * DISABLE_ERS - Define to disable this system. * * ERS_ALIGNED - Alignment of the entries in the blocks. * * ERInterface - Interface of the entry manager. * * ers_new - Allocate an instance of an entry manager. * * ers_report - Print a report about the current state. * * ers_force_destroy_all - Force the destruction of all the managers. * \*****************************************************************************/ /** * Define this to disable the Entry Reusage System. * All code except the typedef of ERInterface will be disabled. * To allow a smooth transition, * @public */ //#define DISABLE_ERS /** * Entries are aligned to ERS_ALIGNED bytes in the blocks of entries. * By default it aligns to one byte, using the "natural order" of the entries. * This should NEVER be set to zero or less. * If greater than one, some memory can be wasted. This should never be needed * but is here just in case some aligment issues arise. * @public * @see #ers_new(uint32) */ #ifndef ERS_ALIGNED # define ERS_ALIGNED 1 #endif /* not ERS_ALIGN_ENTRY */ /** * Public interface of the entry manager. * @param alloc Allocate an entry from this manager * @param free Free an entry allocated from this manager * @param entry_size Return the size of the entries of this manager * @param destroy Destroy this instance of the manager * @public * @see #ers_new(uint32) */ typedef struct eri { /** * Allocate an entry from this entry manager. * If there are reusable entries available, it reuses one instead. * @param self Interface of the entry manager * @return An entry * @protected * @see #ERInterface * @see ERInterface#free(ERInterface,void *) */ void *(*alloc)(struct eri *self); /** * Free an entry allocated from this manager. * WARNING: Does not check if the entry was allocated by this manager. * Freeing such an entry can lead to unexpected behaviour. * @param self Interface of the entry manager * @param entry Entry to be freed * @protected * @see #ERInterface * @see ERInterface#alloc(ERInterface) */ void (*free)(struct eri *self, void *entry); /** * Return the size of the entries allocated from this manager. * @param self Interface of the entry manager * @return Size of the entries of this manager in bytes * @protected * @see #ERInterface */ uint32 (*entry_size)(struct eri *self); /** * Destroy this instance of the manager. * The manager is actually only destroyed when all the instances are destroyed. * When destroying the manager a warning is shown if the manager has * missing/extra entries. * @param self Interface of the entry manager * @protected * @see #ERInterface * @see #ers_new(uint32) */ void (*destroy)(struct eri *self); } *ERInterface; #ifdef DISABLE_ERS // Use memory manager to allocate/free and disable other interface functions # define ers_alloc(obj,type) (type *)aMalloc(sizeof(type)) # define ers_free(obj,entry) aFree(entry) # define ers_entry_size(obj) (uint32)0 # define ers_destroy(obj) // Disable the public functions # define ers_new(size) NULL # define ers_report() # define ers_force_destroy_all() #else /* not DISABLE_ERS */ // These defines should be used to allow the code to keep working whenever // the system is disabled # define ers_alloc(obj,type) (type *)(obj)->alloc(obj) # define ers_free(obj,entry) (obj)->free((obj),(entry)) # define ers_entry_size(obj) (obj)->entry_size(obj) # define ers_destroy(obj) (obj)->destroy(obj) /** * Get a new instance of the manager that handles the specified entry size. * Size has to greater than 0. * If the specified size is smaller than a pointer, the size of a pointer is * used instead. * It's also aligned to ERS_ALIGNED bytes, so the smallest multiple of * ERS_ALIGNED that is greater or equal to size is what's actually used. * @param The requested size of the entry in bytes * @return Interface of the object * @public * @see #ERS_ALIGNED * @see #ERInterface * @see ERInterface#destroy(ERInterface) * @see common\ers.c#ers_new(uint32) */ ERInterface ers_new(uint32 size); /** * Print a report about the current state of the Entry Reusage System. * Shows information about the global system and each entry manager. * The number of entries are checked and a warning is shown if extra reusable * entries are found. * The extra entries are included in the count of reusable entries. * @public * @see common\ers.c#ers_report(void) */ void ers_report(void); /** * Forcibly destroy all the entry managers, checking for nothing. * The system is left as if no instances or entries had ever been allocated. * All previous entries and instances of the managers become invalid. * The use of this is NOT recommended. * It should only be used in extreme situations to make shure all the memory * allocated by this system is released. * @public * @see common\ers.c#ers_force_destroy_all(void) */ void ers_force_destroy_all(void); #endif /* DISABLE_ERS / not DISABLE_ERS */ #endif /* _ERS_H_ */