/******************************************************************* * * ttcache.h 1.1 * * Generic object cache * * Copyright 1996-1999 by * David Turner, Robert Wilhelm, and Werner Lemberg. * * This file is part of the FreeType project, and may only be used * modified and distributed under the terms of the FreeType project * license, LICENSE.TXT. By continuing to use, modify, or distribute * this file you indicate that you have read the license and * understand and accept it fully. * * * This component defines and implements object caches. * * An object class is a structure layout that encapsulate one * given type of data used by the FreeType engine. Each object * class is completely described by: * * - a 'root' or 'leading' structure containing the first * important fields of the class. The root structure is * always of fixed size. * * It is implemented as a simple C structure, and may * contain several pointers to sub-tables that can be * sized and allocated dynamically. * * Examples: TFace, TInstance, TGlyph & TExecution_Context * (defined in 'ttobjs.h') * * - we make a difference between 'child' pointers and 'peer' * pointers. A 'child' pointer points to a sub-table that is * owned by the object, while a 'peer' pointer points to any * other kind of data the object isn't responsible for. * * An object class is thus usually a 'tree' of 'child' tables. * * - each object class needs a constructor and a destructor. * * A constructor is a function which receives the address of * freshly allocated and zeroed object root structure and * 'builds' all the valid child data that must be associated * to the object before it becomes 'valid'. * * A destructor does the inverse job: given the address of * a valid object, it must discard all its child data and * zero its main fields (essentially the pointers and array * sizes found in the root fields). * * * Important notes: * * When the constructor fails to allocate an object, it must * return immediately with an error code, and not try to release * what it has previously allocated before the error. The cache * manager detects the error and calls the destructor on the * partial object, before returning the error to the caller (along * with a NULL pointer for the "new" object). * * The destructor must thus be able to deal with "partial objects", * i.e., objects where only part of the child tables are allocated, * and only release these ones. As the TT_Free() function accepts * a NULL parameter (and returns successfuly in this case), no check * is really necessary when using the macro 'FREE()'. * * Currently, there is no check in the cache manager to see if a * destructor fails (double error state!). * * This scheme is more compact and more maintanable than the one * where de-allocation code is duplicated in the constructor * _and_ the destructor. * * * * Changes between 1.1 and 1.0: * * - introduced the refreshed and finalizer class definition/implementation * - inserted an engine instance pointer in the cache structure * ******************************************************************/ /* $XFree86: xc/extras/FreeType/lib/ttcache.h,v 1.2 2001/10/28 03:32:04 tsi Exp $ */ #ifndef TTCACHE_H #define TTCACHE_H #include "tttypes.h" #include "ttconfig.h" #include "ttmutex.h" #ifdef __cplusplus extern "C" { #endif typedef TT_Error TConstructor( void* object, void* parent ); typedef TT_Error TDestructor ( void* object ); typedef TConstructor TRefresher; typedef TDestructor TFinalizer; typedef TConstructor* PConstructor; typedef TDestructor* PDestructor; typedef TRefresher* PRefresher; typedef TFinalizer* PFinalizer; /* A Cache class record holds the data necessary to define */ /* a cache kind. */ struct TCache_Class_ { ULong object_size; Long idle_limit; PConstructor init; PDestructor done; PRefresher reset; PFinalizer finalize; }; typedef struct TCache_Class_ TCache_Class; typedef TCache_Class* PCache_Class; /* Simple list node record. A list element is said to be 'unlinked' */ /* when it doesn't belong to any list. */ struct TList_Element_; typedef struct TList_Element_ TList_Element; typedef TList_Element* PList_Element; struct TList_Element_ { PList_Element next; void* data; }; /* Simple singly-linked list record - LIFO style, no tail field */ typedef PList_Element TSingle_List; struct TCache_ { PEngine_Instance engine; PCache_Class clazz; /* 'class' is a reserved word in C++ */ TMutex* lock; TSingle_List active; TSingle_List idle; Long idle_count; }; typedef struct TCache_ TCache; typedef TCache* PCache; #if !defined(FTXCMAP_H) && !defined(FTXSBIT_H) /* Returns a new list element, either fresh or recycled. */ /* Note: the returned element is unlinked. */ /* An object cache holds two lists tracking the active and */ /* idle objects that are currently created and used by the */ /* engine. It can also be 'protected' by a mutex. */ /* Initializes a new cache, of class 'clazz', pointed by 'cache', */ /* protected by the 'lock' mutex. Set 'lock' to NULL if the cache */ /* doesn't need protection */ LOCAL_DEF TT_Error Cache_Create( PEngine_Instance engine, PCache_Class clazz, TCache* cache, TMutex* lock ); /* Destroys a cache and all its listed objects */ LOCAL_DEF TT_Error Cache_Destroy( TCache* cache ); /* Extracts a new object from the cache */ LOCAL_DEF TT_Error Cache_New( TCache* cache, void** new_object, void* parent_object ); /* Returns an object to the cache, or discards it depending */ /* on the cache class' 'idle_limit' field */ LOCAL_DEF TT_Error Cache_Done( TCache* cache, void* data ); #define CACHE_New( _cache, _newobj, _parent ) \ Cache_New( (TCache*)_cache, (void**)&_newobj, (void*)_parent ) #define CACHE_Done( _cache, _obj ) \ Cache_Done( (TCache*)_cache, (void*)_obj ) LOCAL_DEF TT_Error TTCache_Init( PEngine_Instance engine ); LOCAL_DEF TT_Error TTCache_Done( PEngine_Instance engine ); #endif /* !FTXCMAP_H && !FTXSBIT_H */ #ifdef __cplusplus } #endif #endif /* TTCACHE_H */ /* END */