core/lib/memb.h

   1 /*
   2  * Copyright (c) 2004, Swedish Institute of Computer Science.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. Neither the name of the Institute nor the names of its contributors
  14  *    may be used to endorse or promote products derived from this software
  15  *    without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27  * SUCH DAMAGE.
  28  *
  29  * This file is part of the Contiki operating system.
  30  *
  31  * Author: Adam Dunkels <adam@sics.se>
  32  *
  33  * $Id: memb.h,v 1.6 2009/04/06 21:18:04 adamdunkels Exp $
  34  */
  35
  36 /**
  37  * \addtogroup mem
  38  * @{
  39  */
  40
  41
  42 /**
  43  * \defgroup memb Memory block management functions
  44  *
  45  * The memory block allocation routines provide a simple yet powerful
  46  * set of functions for managing a set of memory blocks of fixed
  47  * size. A set of memory blocks is statically declared with the
  48  * MEMB() macro. Memory blocks are allocated from the declared
  49  * memory by the memb_alloc() function, and are deallocated with the
  50  * memb_free() function.
  51  *
  52  * @{
  53  */
  54
  55
  56 /**
  57  * \file
  58  *         Memory block allocation routines.
  59  * \author
  60  *         Adam Dunkels <adam@sics.se>
  61  *
  62  */
  63
  64 #ifndef __MEMB_H__
  65 #define __MEMB_H__
  66
  67 #include "sys/cc.h"
  68
  69 /**
  70  * Declare a memory block.
  71  *
  72  * This macro is used to statically declare a block of memory that can
  73  * be used by the block allocation functions. The macro statically
  74  * declares a C array with a size that matches the specified number of
  75  * blocks and their individual sizes.
  76  *
  77  * Example:
  78  \code
  79 MEMB(connections, struct connection, 16);
  80  \endcode
  81  *
  82  * \param name The name of the memory block (later used with
  83  * memb_init(), memb_alloc() and memb_free()).
  84  *
  85  * \param structure The name of the struct that the memory block holds
  86  *
  87  * \param num The total number of memory chunks in the block.
  88  *
  89  */
  90 #define MEMB(name, structure, num) \
  91         static char CC_CONCAT(name,_memb_count)[num]; \
  92         static structure CC_CONCAT(name,_memb_mem)[num]; \
  93         static struct memb name = {sizeof(structure), num, \
  94                                           CC_CONCAT(name,_memb_count), \
  95                                           (void *)CC_CONCAT(name,_memb_mem)}
  96
  97 struct memb {
  98   unsigned short size;
  99   unsigned short num;
 100   char *count;
 101   void *mem;
 102 };
 103
 104 /**
 105  * Initialize a memory block that was declared with MEMB().
 106  *
 107  * \param m A memory block previously declared with MEMB().
 108  */
 109 void  memb_init(struct memb *m);
 110
 111 /**
 112  * Allocate a memory block from a block of memory declared with MEMB().
 113  *
 114  * \param m A memory block previously declared with MEMB().
 115  */
 116 void *memb_alloc(struct memb *m);
 117
 118 /**
 119  * Deallocate a memory block from a memory block previously declared
 120  * with MEMB().
 121  *
 122  * \param m m A memory block previously declared with MEMB().
 123  *
 124  * \param ptr A pointer to the memory block that is to be deallocated.
 125  *
 126  * \return The new reference count for the memory block (should be 0
 127  * if successfully deallocated) or -1 if the pointer "ptr" did not
 128  * point to a legal memory block.
 129  */
 130 char  memb_free(struct memb *m, void *ptr);
 131
 132 int memb_inmemb(struct memb *m, void *ptr);
 133
 134
 135 /** @} */
 136 /** @} */
 137
 138 #endif /* __MEMB_H__ */