Home / Autodocs / exec.library
NAME
- AllocEntry
-
allocate many regions of memory
SYNOPSIS
newMemList = AllocEntry(templateMemList)
D0 A0
struct MemList *AllocEntry(CONST struct MemList *);
D0 A0
struct MemList *AllocEntry(CONST struct MemList *);
FUNCTION
This function takes a MemList structure and allocates enough memory to hold the required memory as well as a MemList structure to keep track of it.
Put another way, the MemList you pass in is a template for the allocations to be performed. AllocEntry() will construct a new MemList which contains the specifified MemEntries found in the template and return a pointer to that new MemList.
These MemList structures may be linked together in a Task control block to keep track of the total memory usage of this Task. RemTask() will automagically free any memory lists attached to the Task's tc_MemEntry list.
Put another way, the MemList you pass in is a template for the allocations to be performed. AllocEntry() will construct a new MemList which contains the specifified MemEntries found in the template and return a pointer to that new MemList.
These MemList structures may be linked together in a Task control block to keep track of the total memory usage of this Task. RemTask() will automagically free any memory lists attached to the Task's tc_MemEntry list.
INPUTS
- templateMemList
-
A MemList structure filled in with MemEntry structures, indicating the type of memory to allocate and also the requested allocation size.
RESULT
- newMemList
-
A new MemList filled in with MemEntry structures, and the actual memory allocated in the MemEntry.me_Addr field, and their sizes in MemEntry.me_Length.
AllocEntry() will try to allocate memory of the specified kind (e.g. MEMF_CHIP, MEMF_FAST, etc.) and size. Any such allocation may fail, e.g. due to lack of free memory, unavailability of the type of memory requested, or memory corruption.
If any of the requested memory allocation fails, AllocEntry() will release the memory already allocated for the MemEntry structures and the new MemList itself. Upon failure, AllocEntry() will return a 32 bit integer which has bit #31 set; bits 0..30 of the integer will contain the MemEntry.me_Reqs value of the respective MemEntry structure for which the allocation failed.
WARNING
AllocEntry() is an unusual memory allocation function which indicates success or failure in a manner which is not consistent with how other memory allocation functions handle the matter.
Note that unlike other such functions, the result of AllocEntry() is never NULL (zero).
AllocEntry() indicates failure by setting bit #31 of the result to 1. Never test if AllocEntry() returns NULL. Here is how it should be done:
Note that if AllocEntry() indicates failure, it will have already freed any memory allocated for the new MemList and its MemEntry structures. You do not need to call FreeEntry().
The result of any memory allocation MUST be checked, and a viable error handling path taken. ANY allocation may fail if memory has been filled.
Memory allocation and deallocation as well as querying how much memory is available requires a Task or, by extension, a Process. None of the exec kernel memory management operations is safe to call from interrupt code!
EXAMPLES
Note that unlike other such functions, the result of AllocEntry() is never NULL (zero).
AllocEntry() indicates failure by setting bit #31 of the result to 1. Never test if AllocEntry() returns NULL. Here is how it should be done:
struct MemList *newMemList;
newMemList = AllocEntry(templateMemList);
if (((ULONG)newMemList) & 0x80000000) == 0)
{
}
else
{
}
newMemList = AllocEntry(templateMemList);
if (((ULONG)newMemList) & 0x80000000) == 0)
{
/* Allocation succeeded */
...
...
else
{
/* Allocation failed */
...
...
The result of any memory allocation MUST be checked, and a viable error handling path taken. ANY allocation may fail if memory has been filled.
Memory allocation and deallocation as well as querying how much memory is available requires a Task or, by extension, a Process. None of the exec kernel memory management operations is safe to call from interrupt code!
EXAMPLES
The user wants five regions of 2, 4, 8, 16, and 32 bytes in size with requirements of MEMF_CLEAR, MEMF_PUBLIC, MEMF_CHIP!MEMF_CLEAR, MEMF_CLEAR, and MEMF_PUBLIC!MEMF_CLEAR respectively. The following code fragment would do that:
MemListDecl:
DS.B LN_SIZE * reserve space for list node DC.W 5 * number of entries DC.L MEMF_CLEAR * entry #0 DC.L 2 DC.L MEMF_PUBLIC * entry #1 DC.L 4 DC.L MEMF_CHIP!MEMF_CLEAR * entry #2 DC.L 8 DC.L MEMF_CLEAR * entry #3 DC.L 16 DC.L MEMF_PUBLIC!MEMF_CLEAR * entry #4 DC.L 32
start:
LEA.L MemListDecl(PC),A0 JSR _LVOAllocEntry(a6) BCLR.L #31,D0 BEQ.S success
-
Type of memory that we failed on is in D0
BUGS
Under Kickstart 1.x (V30-V34) this function may fail to release all the memory allocated if one of the requested allocation fails. The "SetPatch" command on the V1.3 Workbench disks will fix this bug. Note that this bug is not present in Kickstart 2.0 (V36) and beyond.