LibCreatePool

Generate a private memory pool header (V33)

This function is a copy of the pool functions in V39 and up of EXEC. In fact, if you are running in V39, this function will notice and call the EXEC function. This function works in V33 and up (1.2) Amiga system.

The C code interface is _LibCreatePool() and takes its arguments from the stack just like the C code interface for CreatePool() in amiga.lib. The assembly code interface is with the symbol _AsmCreatePool: and takes the parameters in registers with the additional parameter of ExecBase being in a6 which can be used from SAS/C 6 by a prototype of:

memFlags

A memory flags specifier, as taken by AllocMem().

puddleSize

The size of Puddles...

threshSize

The largest allocation that goes into normal puddles. This MUST be less than or equal to puddleSize, (LibCreatePool() will fail if it is not).

newPool

The address of a new pool header, or NULL for error.

The memFlags you specify are used by LibAllocPooled() only, not by LibCreatePool(). The LibCreatePool() function will allocate memory for its management data structures using MEMF_ANY. For example, if you call LibCreatePool(MEMF_FAST, ...) and expect it to return NULL if no fast memory is available you may find that it succeeds. Subsequent LibAllocPooled() calls for this pool will, however, fail on a system without fast memory.

The memory pools solve three problems which allocating memory through AllocMem(), Allocate() and AllocVec() either do not address or which are part of how they have to work:

• Memory pools keep track of the allocations made, so that you may release all of them by calling LibDeletePool() instead of releasing each single allocation separately.
  
  
• Allocating and releasing memory from a pool does not need to involve the Forbid()/Permit() locking which is mandatory for AllocMem(), FreeMem(), etc. Because of how much effort exec.library spends on finding a fitting memory chunk to allocate from and in turn freeing and coalescing freed memory chunks into larger chunks, you would not want this to happen while multitasking is temporarily disabled.
  
  
• Small allocations made from pools no longer affect the overall fragmentation of the available Amiga memory.
  
  

These features benefit not just your application, it also helps every other Amiga software running at the same time.

These benefits come with costs which you should be aware of when making the choice to adopt memory pools for your software.

• Tracking memory allocations can add a noticeable overhead to those allocations which are smaller than or equal to the threshold size given at LibCreatePool() time. This overhead exists because each such small allocation has to be found first when you call LibFreePooled(). The more puddles are in use, the more time it will take to find the puddle which it was allocated from.
  
  
• Only one Task/Process at a time may allocate memory from a pool. This is why AllocMem(), FreeMem(), etc. imply Forbid()/Permit() locking. If your software is sharing a memory pool among several Tasks/Processes then you will have to use an arbitration mechanism such as a SignalSemaphore to allow only a single client at a time to access the pool.
  
  This is of particular importance because pools optimize the layout of the puddles in response to how frequently allocations and deallocations are made from a pool, which is called "bubbling". The more often a puddle is used, the less time will be spent on finding it when releasing an allocation from it.
  
  If no arbitration mechanism is available, you run the risk of corrupting both the pool contents and the memory managed through it.
  
  Sharing the same memory pool among several Tasks/Processes can cause the number of puddles to grow over time which are almost empty but never get memory allocated from them. This is a side-effect of how the layout of the puddles is optimized over time. To avoid this problem you should consider breaking down a single shared memory pool into separate pools if your software architecture permits it.
  
  
• While using memory pools will curb overall memory fragmentation, you may find that fragmentation issues affect the puddles more strongly. If allocations vary greatly in size and do not exceed the threshold value given at LibCreatePool() time you may end up with puddles which are only partly filled, wasting memory. If possible, try to match the puddle size and the threshold size to the allocation sizes you are most likely to use.
  
  

Avoid using a puddle size of 0 bytes. It will have the effect of each LibAllocPooled() call resulting in a separate memory allocation. This defeats the purpose of the memory pools, which is in curbing memory fragmentation and the need to block multitasking when memory has to be allocated from the global pool.

Puddle sizes should not exceed 4294967272 (0xFFFFFFE8) bytes because this may trigger a side-effect leading to far less memory to be allocated.

Creating a pool with MEMF_CLEAR set in the memFlags parameter has a side-effect in slowing down all memory allocations made. The creation of a new puddle will result in it getting set to zero, and any allocation made from that puddle will set it to zero all over again. If you can, avoid using MEMF_CLEAR and set the memory allocated by LibAllocPooled() to zero all by yourself.

DeletePool(), AllocPooled(), FreePooled(), exec/memory.i, LibDeletePool(), LibAllocPooled(), LibFreePooled()