Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Examples

memb.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (c) 2004, Swedish Institute of Computer Science.
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the Institute nor the names of its contributors
00014  *    may be used to endorse or promote products derived from this software
00015  *    without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00027  * SUCH DAMAGE.
00028  *
00029  * This file is part of the Contiki operating system.
00030  *
00031  * Author: Adam Dunkels <adam@sics.se>
00032  *
00033  * $Id: memb.h,v 1.1 2006/06/17 22:41:18 adamdunkels Exp $
00034  */
00035 
00036 /**
00037  * \addtogroup mem
00038  * @{
00039  */
00040 
00041 
00042 /**
00043  * \defgroup memb Memory block management functions
00044  *
00045  * The memory block allocation routines provide a simple yet powerful
00046  * set of functions for managing a set of memory blocks of fixed
00047  * size. A set of memory blocks is statically declared with the
00048  * MEMB() macro. Memory blocks are allocated from the declared
00049  * memory by the memb_alloc() function, and are deallocated with the
00050  * memb_free() function.
00051  *
00052  * \note Because of namespace clashes only one MEMB() can be
00053  * declared per C module, and the name scope of a MEMB() memory
00054  * block is local to each C module.
00055  *
00056  * The following example shows how to declare and use a memory block
00057  * called "cmem" which has 8 chunks of memory with each memory chunk
00058  * being 20 bytes large.
00059  *
00060  * @{
00061  */
00062 
00063 
00064 /**
00065  * \file
00066  *         Memory block allocation routines.
00067  * \author
00068  *         Adam Dunkels <adam@sics.se>
00069  *
00070  */
00071 
00072 #ifndef __MEMB_H__
00073 #define __MEMB_H__
00074 
00075 /*
00076  * Here we define a C preprocessing macro for concatenating to
00077  * strings. We need use two macros in order to allow concatenation of
00078  * two #defined macros.
00079  */
00080 #define MEMB_CONCAT2(s1, s2) s1##s2
00081 #define MEMB_CONCAT(s1, s2) MEMB_CONCAT2(s1, s2)
00082 
00083 /**
00084  * Declare a memory block.
00085  *
00086  * This macro is used to staticall declare a block of memory that can
00087  * be used by the block allocation functions. The macro statically
00088  * declares a C array with a size that matches the specified number of
00089  * blocks and their individual sizes.
00090  *
00091  * Example:
00092  \code
00093 MEMB(connections, sizeof(struct connection), 16);
00094  \endcode
00095  *
00096  * \param name The name of the memory block (later used with
00097  * memb_init(), memb_alloc() and memb_free()).
00098  *
00099  * \param size The size of each memory chunk, in bytes.
00100  *
00101  * \param num The total number of memory chunks in the block.
00102  *
00103  */
00104 #define MEMB(name, structure, num) \
00105         static char MEMB_CONCAT(name,_memb_count)[num]; \
00106         static structure MEMB_CONCAT(name,_memb_mem)[num]; \
00107         static struct memb_blocks name = {sizeof(structure), num, \
00108                                           MEMB_CONCAT(name,_memb_count), \
00109                                           (void *)MEMB_CONCAT(name,_memb_mem)}
00110 
00111 struct memb_blocks {
00112   unsigned short size;
00113   unsigned short num;
00114   char *count;
00115   void *mem;
00116 };
00117 
00118 /**
00119  * Initialize a memory block that was declared with MEMB().
00120  *
00121  * \param m A memory block previosly declared with MEMB().
00122  */
00123 void  memb_init(struct memb_blocks *m);
00124 
00125 /**
00126  * Allocate a memory block from a block of memory declared with MEMB().
00127  *
00128  * \param m A memory block previosly declared with MEMB().
00129  */
00130 void *memb_alloc(struct memb_blocks *m);
00131 
00132 /**
00133  * Deallocate a memory block from a memory block previously declared
00134  * with MEMB().
00135  *
00136  * \param m m A memory block previosly declared with MEMB().
00137  *
00138  * \param ptr A pointer to the memory block that is to be deallocated.
00139  *
00140  * \return The new reference count for the memory block (should be 0
00141  * if successfully deallocated) or -1 if the pointer "ptr" did not
00142  * point to a legal memory block.
00143  */
00144 char  memb_free(struct memb_blocks *m, void *ptr);
00145 
00146 /** @} */
00147 /** @} */
00148 
00149 #endif /* __MEMB_H__ */

Generated on Thu Jun 22 17:45:42 2006 for Contiki 2.x by  doxygen 1.4.4