uIP 1.0: lib/memb.h Source 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 uIP TCP/IP stack
+00030  *
+00031  * Author: Adam Dunkels <adam@sics.se>
+00032  *
+00033  * $Id: memb.h,v 1.1 2006/06/12 08:21:43 adam Exp $
+00034  */
+00035 
+00036 /**
+00037  * \defgroup memb Memory block management functions
+00038  *
+00039  * The memory block allocation routines provide a simple yet powerful
+00040  * set of functions for managing a set of memory blocks of fixed
+00041  * size. A set of memory blocks is statically declared with the
+00042  * MEMB() macro. Memory blocks are allocated from the declared
+00043  * memory by the memb_alloc() function, and are deallocated with the
+00044  * memb_free() function.
+00045  *
+00046  * \note Because of namespace clashes only one MEMB() can be
+00047  * declared per C module, and the name scope of a MEMB() memory
+00048  * block is local to each C module.
+00049  *
+00050  * The following example shows how to declare and use a memory block
+00051  * called "cmem" which has 8 chunks of memory with each memory chunk
+00052  * being 20 bytes large.
+00053  *
+00054  * @{
+00055  */
+00056 
+00057 
+00058 /**
+00059  * \file
+00060  *         Memory block allocation routines.
+00061  * \author
+00062  *         Adam Dunkels <adam@sics.se>
+00063  *
+00064  */
+00065 
+00066 #ifndef __MEMB_H__
+00067 #define __MEMB_H__
+00068 
+00069 /*
+00070  * Here we define a C preprocessing macro for concatenating to
+00071  * strings. We need use two macros in order to allow concatenation of
+00072  * two #defined macros.
+00073  */
+00074 #define MEMB_CONCAT2(s1, s2) s1##s2
+00075 #define MEMB_CONCAT(s1, s2) MEMB_CONCAT2(s1, s2)
+00076 
+00077 /**
+00078  * Declare a memory block.
+00079  *
+00080  * This macro is used to staticall declare a block of memory that can
+00081  * be used by the block allocation functions. The macro statically
+00082  * declares a C array with a size that matches the specified number of
+00083  * blocks and their individual sizes.
+00084  *
+00085  * Example:
+00086  \code
+00087 MEMB(connections, sizeof(struct connection), 16);
+00088  \endcode
+00089  *
+00090  * \param name The name of the memory block (later used with
+00091  * memb_init(), memb_alloc() and memb_free()).
+00092  *
+00093  * \param size The size of each memory chunk, in bytes.
+00094  *
+00095  * \param num The total number of memory chunks in the block.
+00096  *
+00097  */
+00098 #define MEMB(name, structure, num) \
+00099         static char MEMB_CONCAT(name,_memb_count)[num]; \
+00100         static structure MEMB_CONCAT(name,_memb_mem)[num]; \
+00101         static struct memb_blocks name = {sizeof(structure), num, \
+00102                                           MEMB_CONCAT(name,_memb_count), \
+00103                                           (void *)MEMB_CONCAT(name,_memb_mem)}
+00104 
+00105 struct memb_blocks {
+00106   unsigned short size;
+00107   unsigned short num;
+00108   char *count;
+00109   void *mem;
+00110 };
+00111 
+00112 /**
+00113  * Initialize a memory block that was declared with MEMB().
+00114  *
+00115  * \param m A memory block previosly declared with MEMB().
+00116  */
+00117 void  memb_init(struct memb_blocks *m);
+00118 
+00119 /**
+00120  * Allocate a memory block from a block of memory declared with MEMB().
+00121  *
+00122  * \param m A memory block previosly declared with MEMB().
+00123  */
+00124 void *memb_alloc(struct memb_blocks *m);
+00125 
+00126 /**
+00127  * Deallocate a memory block from a memory block previously declared
+00128  * with MEMB().
+00129  *
+00130  * \param m m A memory block previosly declared with MEMB().
+00131  *
+00132  * \param ptr A pointer to the memory block that is to be deallocated.
+00133  *
+00134  * \return The new reference count for the memory block (should be 0
+00135  * if successfully deallocated) or -1 if the pointer "ptr" did not
+00136  * point to a legal memory block.
+00137  */
+00138 char  memb_free(struct memb_blocks *m, void *ptr);
+00139 
+00140 /** @} */
+00141 
+00142 #endif /* __MEMB_H__ */
+