CreatePool

Generate a private memory pool header (V39)

Allocate and prepare a new memory pool header. Each pool is a separate tracking system for memory of a specific type. Any number of pools may exist in the system.

Pools automatically expand and shrink based on demand. Fixed sized "puddles" are allocated by the pool manager when more total memory is needed. Many small allocations can fit in a single puddle. Allocations larger than the threshSize are allocation in their own puddles.

At any time individual allocations may be freed. Or, the entire pool may be removed in a single step.

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 (CreatePool() will fail if it is not)

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

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!

Both AllocPooled() and FreePooled() require an arbitration mechanism to work correctly. The use of ObtainSemaphore()/ReleaseSemaphore() is recommended.

If you port source code written for use on AmigaOS 4 to AmigaOS 3.x, be aware that AmigaOS 4 features an integrated arbitration mechanism which can be activated at pool creation time through the ASOPOOL_Protected tag. Likely, there will be no explicit use of the ObtainSemaphore() and ReleaseSemaphore() functions.

You should make sure that an arbitration mechanism exists for the ported code or you may experience stability issues and undefined behaviour caused by overlapping memory pool operations.

The memFlags you specify are used by AllocPooled() only, not by CreatePool(). The CreatePool() function will allocate memory for its management data structures using MEMF_ANY. For example, if you call CreatePool(MEMF_FAST, ...) and expect it to return NULL if no fast memory is available you may find that it succeeds. Subsequent AllocPooled() 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 DeletePool() 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 CreatePool() time. This overhead exists because each such small allocation has to be found first when you call FreePooled(). 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 CreatePool() 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 AllocPooled() 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 AllocPooled() to zero all by yourself.

DeletePool(), AllocPooled(), FreePooled(), "exec/memory.i"