/*******************************************************************
*
* 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
*
******************************************************************/
#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;
/* 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 );
#ifdef __cplusplus
}
#endif
#endif /* TTCACHE_H */
/* END */