Woolz Image Processing Version 1.4.0
AlcType.h
Go to the documentation of this file.
00001 #ifndef ALCTYPE_H
00002 #define ALCTYPE_H
00003 #if defined(__GNUC__)
00004 #ident "University of Edinburgh $Id: cdb8479801a10daa05b5514dd4268c2f9e675b1c $"
00005 #else
00006 static char _AlcType_h[] = "University of Edinburgh $Id: cdb8479801a10daa05b5514dd4268c2f9e675b1c $";
00007 #endif
00008 /*!
00009 * \file         libAlc/AlcType.h
00010 * \author       Bill Hill
00011 * \date         March 1999
00012 * \version      $Id: cdb8479801a10daa05b5514dd4268c2f9e675b1c $
00013 * \par
00014 * Address:
00015 *               MRC Human Genetics Unit,
00016 *               MRC Institute of Genetics and Molecular Medicine,
00017 *               University of Edinburgh,
00018 *               Western General Hospital,
00019 *               Edinburgh, EH4 2XU, UK.
00020 * \par
00021 * Copyright (C), [2012],
00022 * The University Court of the University of Edinburgh,
00023 * Old College, Edinburgh, UK.
00024 * 
00025 * This program is free software; you can redistribute it and/or
00026 * modify it under the terms of the GNU General Public License
00027 * as published by the Free Software Foundation; either version 2
00028 * of the License, or (at your option) any later version.
00029 *
00030 * This program is distributed in the hope that it will be
00031 * useful but WITHOUT ANY WARRANTY; without even the implied
00032 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
00033 * PURPOSE.  See the GNU General Public License for more
00034 * details.
00035 *
00036 * You should have received a copy of the GNU General Public
00037 * License along with this program; if not, write to the Free
00038 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
00039 * Boston, MA  02110-1301, USA.
00040 * \brief        Type definitions for the Woolz type allocation
00041 *               library.
00042 */
00043 
00044 #ifndef WLZ_EXT_BIND
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 #endif /* WLZ_EXT_BIND */
00049 
00050 /*!
00051 * \enum         _AlcErrno
00052 * \ingroup      AlcError
00053 * \brief        Error codes returned by functions of the
00054 *               memory allocation and fundamental type library.
00055 *               Typedef: ::AlcErrno
00056 */
00057 typedef enum _AlcErrno
00058 {
00059   ALC_ER_NONE = 0,              /*!< Noe error */
00060   ALC_ER_ALLOC,                 /*!< Memory allocation error */
00061   ALC_ER_NULLPTR,               /*!< Null pointer detected */
00062   ALC_ER_NUMELEM,               /*!< Inappropriate number of elements */
00063   ALC_ER_PARAM,                 /*!< Inappropriate function paramerter */
00064   ALC_ER_READ,                  /*!< File read failure */
00065   ALC_ER_WRITE                  /*!< File write failure */
00066 } AlcErrno;
00067 
00068 
00069 /*!
00070 * \struct       _AlcBlockStack
00071 * \ingroup      AlcBlockStack
00072 * \brief        General purpose data structure for maintaining blocks
00073 *               of some data type. Useful for efficient memory allocation.
00074 *               It's not a stack but a doubly linked list of blocks of
00075 *               data which can be used as a stack, heap, list, ....
00076 *               Typedef: ::AlcBlockStack
00077 */
00078 typedef struct _AlcBlockStack
00079 {
00080   size_t           elmCnt;      /*!< Number of elements used in block */
00081   size_t           maxElm;      /*!< Number of elements space allocated for
00082                                      in block */
00083   void          *elements;      /*!< Block of elements */
00084   struct _AlcBlockStack *prev;  /*!< Previous block up in stack */
00085   struct _AlcBlockStack *next;  /*!< Next block down, remember it's a
00086                                      doubly linked list not a stack! */
00087 } AlcBlockStack;
00088 
00089 #ifndef WLZ_EXT_BIND
00090 /*!
00091 * \typedef      AlcLRUCKeyFn
00092 * \ingroup      AlcLRUCache
00093 * \brief        Function called to compute a ::AlcLRUCache item's numeric
00094 *               key given it's entry.
00095 *               The required function parameters are the cache and the
00096 *               entry.
00097 */
00098 struct _AlcLRUCache;
00099 typedef unsigned int (*AlcLRUCKeyFn)(struct _AlcLRUCache *, void *);
00100 
00101 /*!
00102 * \typedef      AlcLRUCCmpFn
00103 * \ingroup      AlcLRUCache
00104 * \brief        Function called to compare two entries in a ::AlcLRUCache.
00105 *               This function must return zero only iff the two entries
00106 *               match.
00107 *               The required function parameters are the two cache entry
00108 *               data structures with sufficient fields set to make a
00109 *               comparison.
00110 */
00111 typedef int     (*AlcLRUCCmpFn)(const void *, const void *);
00112 
00113 /*!
00114 * \typedef      AlcLRUCCmpFn
00115 * \ingroup      AlcLRUCache
00116 * \brief        Function called when a ::AlcLRUCache item is unlinked and
00117 *               removed from the cache. It may be used, for example, to
00118 *               free the item's entry.
00119 *               The required function parameters are the cache and the
00120 *               entry that will be unlinked and removed.
00121 */
00122 struct _AlcLRUCache;
00123 struct _AlcLRUCItem;
00124 typedef void    (*AlcLRUCUnlinkFn)(struct _AlcLRUCache *, void *);
00125 
00126 /*!
00127 * \struct       _AlcLRUCItem
00128 * \ingroup      AlcLRUCache
00129 * \brief        A cache item for a ::AlcLRUCache.
00130 *               Typedef: ::AlcLRUCItem
00131 */
00132 typedef struct  _AlcLRUCItem
00133 {
00134   unsigned int  key;            /*!< Numeric key used as input to a hash
00135                                      function to locate the item. */
00136   size_t        sz;             /*!< Size of the item's entry. */
00137   void          *entry;         /*!< User supplied entry. */
00138   struct _AlcLRUCItem *rankPrv; /*!< Previous item in priority rank table. */
00139   struct _AlcLRUCItem *rankNxt; /*!< Next item in priority rank table. */
00140   struct _AlcLRUCItem *hashNxt; /*!< Next item in hash table or free
00141                                      item list. */
00142 } AlcLRUCItem;
00143 
00144 /*!
00145 * \struct       _AlcLRUCache
00146 * \ingroup      AlcLRUCache
00147 * \brief        A least recent use removal cache allowing rank and random
00148 *               access to it's entries. Rank access is via a doubly linked
00149 *               list (using rankPrv and rankNxt), while random access is
00150 *               via hash table (using the item's key and hashNxt).
00151 *               The cache will unlink items as required to maintain the
00152 *               set maximum number of entries and maximum total entry
00153 *               size.
00154 *               Typedef: ::AlcLRUCache
00155 */
00156 typedef struct  _AlcLRUCache
00157 {
00158   unsigned int  numItem;        /*!< Current number of items in the cache. */
00159   unsigned int  maxItem;        /*!< Maximum number of items in the cache. */
00160   size_t        curSz;          /*!< Current total cache size. */
00161   size_t        maxSz;          /*!< Maximum total cache size. */
00162   unsigned int  hashTblSz;      /*!< Size of the hash table. */
00163   unsigned int  itemBlkSz;      /*!< Number of items to allocate in a block. */
00164   AlcLRUCKeyFn  keyFn;          /*!< Function called to compute a numeric
00165                                      key for an entry. */
00166   AlcLRUCCmpFn  cmpFn;          /*!< Function called to compare two entries,
00167                                      returning zero only iff the entries
00168                                      match. */
00169   AlcLRUCUnlinkFn unlinkFn;     /*!< Function called before unlinking and
00170                                      removing an item from the cache. */
00171   struct _AlcBlockStack *freeStack; /*!< Stack of blocks of items. */
00172   struct _AlcLRUCItem *freeList; /*!< Head of the linked list of free cache
00173                                       items available for use. */
00174   struct _AlcLRUCItem *rankHead; /*!< Head of the linked list of cache items
00175                                       in priority rank order. This is
00176                                       maintained with the most recently used
00177                                       item at the head and the least recently
00178                                       used item at the tail. */
00179   struct _AlcLRUCItem *rankTail; /*!< Tail of the linked list of cache items
00180                                       in rank order. */
00181   struct _AlcLRUCItem **hashTbl; /*!< Hash table of cache items. */
00182 } AlcLRUCache;
00183 #endif /* WLZ_EXT_BIND */
00184 
00185 /*!
00186 * \struct       _AlcCPQQueue
00187 * \ingroup      AlcCPQ
00188 * \brief        An \f$O(1)\f$ priority queue based on the Calendar
00189 *               Priority Queue data structure.
00190 *               Typedef: ::AlcCPQQueue.
00191 */
00192 typedef struct _AlcCPQQueue
00193 {
00194   int           nItem;          /*!< Number of items in the queue. */
00195   int           nBucket;        /*!< Number of buckets for items. */
00196   int           nItemIncThr;    /*!< Threshold number of items, at
00197                                      which the number of buckets is
00198                                      increased. */
00199   int           nItemDecThr;    /*!< Threshold number of items, at
00200                                      which the number of buckets is
00201                                      decreased. */
00202   int           lastIdx;        /*!< The index (offset by bucketBase) of
00203                                      the last bucket from which an item
00204                                      was dequeued or the index of a top
00205                                      priority item that has been inserted.
00206                                      A negative value is used to indicate
00207                                      that the index is invalid. */
00208   int           itemBlockSz;    /*!< Number of items allocated in each
00209                                      block by AlcBlockStackNew(). */
00210   int           bucketBase;     /*!< The offset into the allocated buckets
00211                                      of the current buckets. */
00212   int           maxBucket;      /*!< The total number of buckets that have
00213                                      been allocated. */
00214   int           resizable;      /*!< Non-zero if the queue is resizable. */
00215   float         lastPriority;   /*!< The priority of either the last item
00216                                      dequeued or of the top priority item
00217                                      that has been inserted. */
00218   double        bucketWidth;    /*!< The width of each bucket. */
00219   double        bucketMin;      /*!< The minimum priority for the bucket
00220                                      with (offset) index lastIdx. A negative
00221                                      value is used to indicate that the
00222                                      minimum priority is invalid. */
00223   struct _AlcCPQItem **buckets; /*!< Contiguous array of buckets. */
00224   struct _AlcCPQItem *freeItem; /*!< List of items available for use in the
00225                                      priority queue. */
00226   struct _AlcBlockStack *freeStack; /*!< Free stack used to efficiently
00227                                      allocate and free blocks of queue
00228                                      items. */
00229 } AlcCPQQueue;
00230 
00231 /*!
00232 * \struct       _AlcCPQItem
00233 * \ingroup      AlcCPQ
00234 * \brief        An item in a calendar priority queue.
00235 *               Typedef: ::AlcCPQItem.
00236 */
00237 typedef struct _AlcCPQItem
00238 {
00239   float         priority;       /*!< Priority of the item, which must be
00240                                      \f$ \geq 0\f$. Priority is greater
00241                                      for greater priority values. */
00242   void          *entry;         /*!< User supplied entry. May be NULL. */
00243   struct _AlcCPQItem *prev;     /*!< Previous item in bucket or free
00244                                      item list. */
00245   struct _AlcCPQItem *next;     /*!< Next item in bucket or free
00246                                      item list. */
00247 } AlcCPQItem;
00248 
00249 /*!
00250 * \enum         _AlcDirection
00251 * \ingroup      AlcBlockStack
00252 * \brief        Data structure traversal direction.
00253 *               Typedef: ::AlcDirection
00254 */
00255 typedef enum _AlcDirection
00256 {
00257   ALC_DIRECTION_FWD,            /*!< Towards end of a data structure,
00258                                      eg the tail of a list */
00259   ALC_DIRECTION_REV             /*!< Towards begining of a data structure,
00260                                      eg the head of a list */
00261 } AlcDirection;
00262 
00263 
00264 /*!
00265 * \struct       _AlcDLPItem
00266 * \ingroup      AlcDLPList
00267 * \brief        A doubly linked list item.
00268 *               Typedef: ::AlcDLPItem
00269 */
00270 typedef struct _AlcDLPItem
00271 {
00272 #ifdef WLZ_EXT_BIND
00273   void          *freeFn;
00274 #else /* WLZ_EXT_BIND */
00275   void          (*freeFn)(void *); /*!< Function to free list item, may be
00276                                         NULL */
00277 #endif /* WLZ_EXT_BIND */
00278   void          *entry;         /*!< The list item's entry */
00279   struct _AlcDLPItem *next;     /*!< The next item in the list, towards the
00280                                      tail of the list*/
00281   struct _AlcDLPItem *prev;     /*!< The previous item in the list, towards
00282                                      the head of the list */
00283 } AlcDLPItem;
00284 
00285 /*!
00286 * \struct       _AlcDLPList
00287 * \ingroup      AlcDLPList
00288 * \brief        A doubly linked list of pointers.
00289 *               Typedef: ::AlcDLPList
00290 */
00291 typedef struct _AlcDLPList
00292 {
00293   AlcDLPItem *head;             /*!< The head of the list */
00294 } AlcDLPList;
00295 
00296 #ifndef WLZ_EXT_BIND
00297 /*!
00298 * \struct       _AlcHashItem
00299 * \ingroup      AlcHashTable
00300 * \brief        A hash table item.
00301 *               Typedef: ::AlcHashItem
00302 */
00303 typedef struct _AlcHashItem
00304 {
00305   void          (*freeFn)(void *); /*!< Function to free the hash item, may
00306                                         be NULL */
00307   void          *entry;         /*!< The hash item's entry */
00308   void          *key;           /*!< The key which identifies the hash item */
00309   struct _AlcHashItem *next;    /*!< Next item in the hash tables linked list,
00310                                      NULL if this is the last item */
00311   struct _AlcHashItem *prev;    /*!< Previous item in the hash tables linked
00312                                      list, NULL if this is the first item */
00313 } AlcHashItem;
00314 
00315 /*!
00316 * \struct       _AlcHashTable
00317 * \ingroup      AlcHashTable
00318 * \brief        A hash table.
00319 *               Typedef: ::AlcHashTable
00320 */
00321 typedef struct _AlcHashTable
00322 {
00323   int           (*keyCmp)(void *, void *); /*!< Key comparison function */
00324   size_t        (*hashFn)(void *);         /*!< The hashing function */
00325   size_t        tableSz;                   /*!< Number of list slots in the
00326                                                 hash table */
00327   AlcHashItem   **table;                   /*!< Table of lists */
00328 } AlcHashTable;
00329 #endif /* WLZ_EXT_BIND */
00330 
00331 
00332 /*!
00333 * \struct       _AlcVector
00334 * \ingroup      AlcVector
00335 * \brief        An extensible 1D array.
00336 *               Typedef: ::AlcVector
00337 */
00338 typedef struct _AlcVector
00339 {
00340   size_t        elmSz;          /*!< Size of elements of the vector */
00341   size_t        blkCnt;         /*!< Number of block pointers */
00342   size_t        blkUse;         /*!< Number of blocks used */
00343   size_t        blkSz;          /*!< Number of elements in a block, must NOT be
00344                                      changed once vector has been created! */
00345   void          *freeStack;     /*!< Free stack */
00346   void          **blocks;       /*!< Data blocks */
00347 } AlcVector;
00348 
00349 /*!
00350 * \enum         _AlcPointType
00351 * \brief        Type of coordinate point.
00352 *               Typedef: ::AlcPointType
00353 */
00354 
00355 typedef enum _AlcPointType
00356 {
00357   ALC_POINTTYPE_INT,            /*!< Integer point */
00358   ALC_POINTTYPE_DBL             /*!< Double precision floating point point */
00359 } AlcPointType;
00360 
00361 /*!
00362 * \union        _AlcPointP
00363 * \brief        Pointer to a generic coordinate.
00364 *               Typedef: ::AlcPointP
00365 */
00366 typedef union _AlcPointP
00367 {
00368   void          *kV;            /*!< Pointer to any point */
00369   int           *kI;            /*!< Pointer to an integer point */
00370   double        *kD;            /*!< Pointer to a double precision floating
00371                                      point point */
00372 } AlcPointP;
00373 
00374 
00375 /*!
00376 * \struct       _AlcKDTNode
00377 * \ingroup      AlcKDTree
00378 * \brief        A node in a binary space partition tree (kD-tree).
00379 *               Typedef: ::AlcKDTNode
00380 */
00381 typedef struct _AlcKDTNode
00382 {
00383   size_t        idx;            /*!< Index or identifier for the node */
00384   int           split;          /*!< The splitting dimension */
00385   struct _AlcKDTNode *parent;   /*!< The parent node, NULL if the node is
00386                                      the root of the tree */
00387   struct _AlcKDTNode *childN;   /*!< Child node with -ve comparision result */
00388   struct _AlcKDTNode *childP;   /*!< Child node with +ve comparision result */
00389   AlcPointP     key;            /*!< The node's key value */
00390   AlcPointP     boundN;         /*!< Coordinate of the minimum bounding box
00391                                      values */
00392   AlcPointP     boundP;         /*!< Coordinate of the maximum bounding box
00393                                      values */
00394 } AlcKDTNode;
00395 
00396 /*!
00397 * \struct       _AlcKDTTree
00398 * \ingroup      AlcKDTree
00399 * \brief        A binary space partition tree (kD-tree).
00400 *               Typedef: ::AlcKDTTree
00401 */
00402 typedef struct _AlcKDTTree
00403 {
00404    AlcPointType type;           /*!< The type of tree, ie the type of node
00405                                      key */
00406   int           dim;            /*!< Dimension of the tree. */
00407   size_t        keySz;          /*!< sizeof(key) * dimension */
00408   double        tol;            /*!< Comparision tollerance for double key
00409                                      values */
00410   size_t        nNodes;         /*!< Number of nodes in the tree */
00411   struct _AlcKDTNode *root;     /*!< The root node of the tree. */
00412   struct _AlcKDTNode *nodeStack; /*!< Stack of nodes available for use */
00413   size_t        nodeBlockSz;    /*!< Number of nodes allocated in a block */
00414   AlcBlockStack *freeStack;     /*!< Stack of allocated node blocks */
00415 } AlcKDTTree;
00416 
00417 /*!
00418 * \struct       _AlcHeapEntryCore
00419 * \ingroup      AlcHeap
00420 * \brief        Core heap entry data structure. All other heap entry
00421 *               data structures must have the fields of this data
00422 *               structure first.
00423 *               Typedef: ::AlcHeapEntryCore
00424 */
00425 typedef struct _AlcHeapEntryCore
00426 {
00427   double                priority;       /*!< Entry priority highest priority
00428                                              at the head of the queue. */
00429 } AlcHeapEntryCore;
00430 
00431 /*!
00432 * \struct       _AlcHeap
00433 * \ingroup      AlcHeap
00434 * \brief        A general purpose heap data structure.
00435 *               Typedef: ::AlcHeap
00436 */
00437 typedef struct _AlcHeap
00438 {
00439   int                   nEnt;           /*!< Number of entries in use:
00440                                              incremented when entry inserted,
00441                                              no change is popped,
00442                                              decremented when entry freed. */
00443   int                   maxEnt;         /*!< Number of entries allocated. */
00444   int                   entInc;         /*!< When allocating space for more
00445                                              entries, allocate space for
00446                                              this many at a time. */
00447   int                   entSz;          /*!< Size of each heap entry. */
00448   void                  *data;          /*!< Application data. */
00449   void                  *entries;       /*!< Allocated heap entries. */
00450 } AlcHeap;
00451 
00452 #ifndef WLZ_EXT_BIND
00453 #ifdef __cplusplus
00454 }                                              /* Close scope of 'extern "C" */
00455 #endif
00456 #endif /* WLZ_EXT_BIND */
00457 
00458 #endif /* ALCTYPE_H */