[Contents] [Index] [Help] [Retrace] [browse <] [Browse >]


NAME
    Allocate - allocate a block of memory

SYNOPSIS
    memoryBlock=Allocate(memHeader, byteSize)
    D0                   A0         D0

    void *Allocate(struct memheader *, ulong);

FUNCTION
    This function is used to allocate blocks of memory from a given
    private free memory pool (as specified by a memheader and its
    memory chunk list).  Allocate will return the first free block that
    is greater than or equal to the requested size.

    All blocks, whether free or allocated, will be block aligned;
    hence, all allocation sizes are rounded up to the next block even
    value (e.g. the minimum allocation resolution is currently 8
    bytes.  A request for 8 bytes will use up exactly 8 bytes.  A
    request for 7 bytes will also use up exactly 8 bytes.).

    This function can be used to manage an application's internal data
    memory.  Note that no arbitration of the memheader and associated
    free chunk list is done.  You must be the owner before calling
    Allocate.

INPUTS
    memHeader - points to the local memory list header.
    byteSize - the size of the desired block in bytes.

RESULT
    memoryBlock - a pointer to the just allocated free block.
           If there are no free regions large enough to satisfy the
           request, return zero.

EXAMPLE
    #include <exec/types.h>
    #include <exec/memory.h>
    void *AllocMem();
    #define BLOCKSIZE 4096L /* Or whatever you want */

    void main()
    {
    struct memheader *mh;
    struct memchunk  *mc;
    APTR   block1;
    APTR   block2;

        /* Get the memheader needed to keep track of our new block */
        mh = (struct memheader *)
             AllocMem((long)sizeof(struct MemHeader), MEMF_CLEAR );
        if( !mh )
            exit(10);

        /* Get the actual block the above memheader will manage */
        mc = (struct memchunk *)allocmem( blocksize, 0l );
        if( !mc )
            {
            FreeMem( mh, (long)sizeof(struct MemHeader) ); exit(10);
            }

        mh->mh_Node.ln_Type = NT_MEMORY;
        mh->mh_Node.ln_Name = "myname";
        mh->mh_First = mc;
        mh->mh_Lower = (APTR) mc;
        mh->mh_Upper = (APTR) ( BLOCKSIZE + (ULONG) mc );
        mh->mh_Free  = BLOCKSIZE;

        /* Set up first chunk in the freelist */
        mc->mc_Next  = NULL;
        mc->mc_Bytes = BLOCKSIZE;

        block1 = (APTR) Allocate( mh, 20L );
        block2 = (APTR) Allocate( mh, 314L );
        printf("mh=$%lx mc=$%lxn",mh,mc);
        printf("Block1=$%lx, Block2=$%lxn",block1,block2);

        FreeMem( mh, (long)sizeof(struct MemHeader) );
        FreeMem( mc, BLOCKSIZE );
    }

NOTE
    If the free list is corrupt, the system will panic with alert
    AN_MemCorrupt, $01000005.

SEE ALSO
    Deallocate, exec/memory.h