[Anet-checkins] CVS: ANet/ANet_Daemon/Common Memory.c,NONE,1.1 Memory.h,1.3,1.4

[Benoit N. <be...@us...>]

Update of /cvsroot/anet/ANet/ANet_Daemon/Common
In directory usw-pr-cvs1:/tmp/cvs-serv21699/Common

Modified Files:
	Memory.h 
Added Files:
	Memory.c 
Log Message:
Documented MMStubs

--- NEW FILE: Memory.c ---
/******************************************************************
        ANet_Daemon/Common/Memory.c
        Memory management for the run-time wrapper of the daemon.
        
        Part of the ANet project.
        
        Distributed under GPL: http://www.gnu.org/copyleft/gpl.html
******************************************************************/

#include "Memory.h"
#include <stdlib.h>

/*!
  \addtogroup memory
  \{
*/

/*!
  \file
  \brief Memory management code
  \author Benad
*/

/*
  Current memory format:
  ANetMemoryTag is a memory location.
  The first 4 bytes are the size of the block.
  The remaining bytes is the data itself.
*/

/*!
  \brief Checks if an <CODE>ANetMemoryTag</CODE> is valid.
  \param tag The tag to check.
  \return Any non-zero value if the tag is valid. <CODE>0</CODE>
  otherwise.

  This function checks for the validity of an <CODE>ANetMemoryTag</CODE>.
*/
UInt32 IsTagValid(ANetMemoryTag tag)
{
  return (tag != 0); 
}

/*!
  \brief Creates a new memory block
  \param size The size, in bytes, of the memory block to create.
  \param flags Flags for the new memory block. Currently
  ignored; use <CODE>0</CODE>.
  \return A memory tag that represents the new memory block.

  This function creates a new memory block. It returns a new
  <CODE>ANetMemoryTag</CODE> which can be used with other
  functions.
  \par
  Use <CODE>IsTagValid()</CODE> to make sure the tag was
  generated properly and no error occured.
  \see IsTagValid()
*/
ANetMemoryTag NewMemoryBlock(UInt32 size, UInt32 flags)
{
  // Soft-limit of 500MB assumed
  UInt32 *mem;
  if (size & 0xC0000000)
  {
    return (ANetMemoryTag)(0);
  }
  mem = (UInt32*)(malloc(size + sizeof(UInt32)));
  mem[0] = size;
  return (ANetMemoryTag)(mem);
}

/*!
  \brief Deletes a memory block.
  \param tag <CODE>ANetMemoryTag</CODE> to the block to delete.
  \return
  \li <CODE>0</CODE>: No error.
  \li <CODE>1</CODE>: Tag is invalid.

  This deletes a memory block generated by a previous call
  to <CODE>NewMemoryBlock()</CODE>.
  \see NewMemoryBlock()
*/
UInt32 DeleteMemoryBlock(ANetMemoryTag tag)
{
  if (!tag)
    return 1;
  free((char*)(tag));
  return 0;
}

/*!
  \brief Gets the size of a memory block.
  \param tag <CODE>ANetMemoryTag</CODE> to the memory block.
  \return The size, in bytes, of the memory block.

  This function returns the size of a memory block.
  \par
  The returned value is unexpected if <CODE>tag</CODE> is not valid,
  but the function should not produce any other error.
  \see IsTagValid()
*/
UInt32 GetMemoryBlockSize(ANetMemoryTag tag)
{
  return *(UInt32*)(tag);
}

/*!
  \brief Resolves an <CODE>ANetMemoryTag</CODE>.
  \param tag The <CODE>ANetMemoryTag</CODE>.
  \param ptr The address of the pointer to set.
  \return
  \li <CODE>0</CODE>: No error.
  \li <CODE>1</CODE>: Invalid <CODE>tag</CODE> value.
  \li <CODE>2</CODE>: Invalid <CODE>ptr</CODE> value.

  This function returns a pointer to the beginning
  of a memory block pointed by an <CODE>ANetMemoryTag</CODE>.
  \warning The pointer returned is valid only within the scope
  of the function that called <CODE>ResolveMemoryTag</CODE>.
  That pointer might become invalid as soon as your function
  returns.
*/
UInt32 ResolveMemoryTag(ANetMemoryTag tag, UInt8 **ptr)
{
  // Soft-limit of 500MB assumed
  if (!tag)
    return 1;
  if (!ptr)
    return 2;
  if (*((UInt32*)(tag)) & 0xC0000000)
    return 1;
  *ptr = (UInt8*)((UInt32*)(tag) + 1);
  return 0;
}

/*! \} */


Index: Memory.h
===================================================================
RCS file: /cvsroot/anet/ANet/ANet_Daemon/Common/Memory.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** Memory.h	2001/11/05 23:27:03	1.3
--- Memory.h	2001/12/22 21:36:08	1.4
***************
*** 11,18 ****
--- 11,57 ----
  #define ANET_MEMORY
  
+ /*!
+   \addtogroup memory Memory Management Utilities
+   \ingroup utils
+   \brief Memory management utilites for the daemon
+ 
+   Those functions are used to create, change, delete and manage
+   memory blocks allocated in the daemon's memory partition.
+   \par
+   Their implementation is totoally cross-platform yet are much more
+   flexible than what is offered by the functions offered in the
+   ANSI C libraries.
+   \par
+   While use of those functions is not essential, it is
+   highly recommended. Any data stored in a memory block
+   generated by those functions can be tracked (for leak detection),
+   stored on hard disk and relocated transparently.
+   \{
+ */
+ 
+ /*!
+   \file
+   \brief Memory management declarations
+   \author Benad
+ */
+ 
  #include "ANetCommon.h"
  
+ /*!
+   \struct ANetMemoryTag
+   \brief Opaque memory tag
+ 
+   <CODE>ANetMemoryTag</CODE> represents a memory block in memory.
+   It is "opaque" in the sense that you are not supposed to know
+   what its contents are. To access to the contents of the memory
+   block represented by an <CODE>ANetMemoryTag</CODE>, use
+   the function <CODE>ResolveMemoryTag</CODE>.
+   \see ResolveMemoryTag()
+ */
+ 
  typedef UInt32 ANetMemoryTag;
  
+ UInt32 IsTagValid(ANetMemoryTag tag);
+ 
  ANetMemoryTag NewMemoryBlock(UInt32 size, UInt32 flags);
  UInt32 DeleteMemoryBlock(ANetMemoryTag tag);
***************
*** 21,22 ****
--- 60,63 ----
  
  #endif
+ 
+ /*! \} */