Exec Memory Pools - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:09:52Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:09, 26 January 2025
Line 31:		Line 31:
	If successful, AllocSysObject() returns the address of the memory pool.		If successful, AllocSysObject() returns the address of the memory pool.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,		APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
	ASOPOOL_Puddle, 4096,		ASOPOOL_Puddle, 4096,
Line 55:		Line 55:
	Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.		Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Rectangle *rect = IExec->AllocPooled(mem_pool, sizeof(struct Rectangle);		struct Rectangle *rect = IExec->AllocPooled(mem_pool, sizeof(struct Rectangle);

Line 70:		Line 70:
	An application can free a block of memory it allocated from a pool by calling FreePooled():		An application can free a block of memory it allocated from a pool by calling FreePooled():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->FreePooled(mem_pool, mem_drop, mem_size);		IExec->FreePooled(mem_pool, mem_drop, mem_size);
	</syntaxhighlight>		</syntaxhighlight>
Line 80:		Line 80:
	A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.		A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->FreeSysObject(ASOT_MEMPOOL, mem_pool);		IExec->FreeSysObject(ASOT_MEMPOOL, mem_pool);
	</syntaxhighlight>		</syntaxhighlight>
Line 90:		Line 90:
	Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.		Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,		APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
	ASOPOOL_MFlags, MEMF_SHARED,		ASOPOOL_MFlags, MEMF_SHARED,

Daniel Jedlicka: Fixed a typo: MEMF_CLEARED doesn't exist.

2016-04-09T19:36:35Z

Fixed a typo: MEMF_CLEARED doesn't exist.

← Older revision		Revision as of 19:36, 9 April 2016
Line 27:		Line 27:
	== Creating a Memory Pool ==		== Creating a Memory Pool ==

	You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The ~~MEMF_CLEARED~~ flag may also be specified to automatically clear memory allocated from the pool.		You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEAR flag may also be specified to automatically clear memory allocated from the pool.

	If successful, AllocSysObject() returns the address of the memory pool.		If successful, AllocSysObject() returns the address of the memory pool.
Line 127:		Line 127:
	\| Free pooled memory allocated with AllocVecPooled().		\| Free pooled memory allocated with AllocVecPooled().
	\|}		\|}

			=== Obsolete ===

	These Exec functions are now practically obsolete and not recommended for use in new code:		These Exec functions are now practically obsolete and not recommended for use in new code:

Daniel Jedlicka: Memory Pool Organization: fixed a typo.

2015-08-23T18:24:48Z

Memory Pool Organization: fixed a typo.

← Older revision		Revision as of 18:24, 23 August 2015
Line 17:		Line 17:
	When you create a pool, you specify the size of its puddles and a threshold value, not the size of the pool. This is because memory pools are dynamic, they have no fixed size. The pool manager takes the memory for your application from the puddles. As you require memory, the pool manager expands the pool by adding puddles, and as you free memory, the pool manager shrinks the pool by deleting puddles.		When you create a pool, you specify the size of its puddles and a threshold value, not the size of the pool. This is because memory pools are dynamic, they have no fixed size. The pool manager takes the memory for your application from the puddles. As you require memory, the pool manager expands the pool by adding puddles, and as you free memory, the pool manager shrinks the pool by deleting puddles.

	The size of the puddles is important because the pool manager will try to use as much of a puddle as possible before adding a new puddle. Each time you allocate memory from the pool, the pool manager takes the memory from a puddle unless an allocation exceeds the amount of memory remaining in a puddle. If the allocation request exceeds the memory remaining in a puddle, the pool manager adds a new puddle. If the allocation exceeds the pool's puddle size, the pool manager will create a special over sized puddle to accommodate the ~~application~~.		The size of the puddles is important because the pool manager will try to use as much of a puddle as possible before adding a new puddle. Each time you allocate memory from the pool, the pool manager takes the memory from a puddle unless an allocation exceeds the amount of memory remaining in a puddle. If the allocation request exceeds the memory remaining in a puddle, the pool manager adds a new puddle. If the allocation exceeds the pool's puddle size, the pool manager will create a special over-sized puddle to accommodate the allocation.

	The key is to use all the drops in a puddle. If you create a pool with puddles of 200 bytes and allocate 150 bytes at a time, you'll waste 50 bytes in every puddle. Set the puddle size in accordance with your memory requirements.		The key is to use all the drops in a puddle. If you create a pool with puddles of 200 bytes and allocate 150 bytes at a time, you'll waste 50 bytes in every puddle. Set the puddle size in accordance with your memory requirements.
Line 23:		Line 23:
	The threshold value is the size of the largest allocation to use within a single puddle. An allocation request larger than the threshold value causes the pool manager to add a new puddle. Ideally, the threshold value should be the size of the largest allocation you will make.		The threshold value is the size of the largest allocation to use within a single puddle. An allocation request larger than the threshold value causes the pool manager to add a new puddle. Ideally, the threshold value should be the size of the largest allocation you will make.

	The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.		The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size, so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.

	== Creating a Memory Pool ==		== Creating a Memory Pool ==

Daniel Jedlicka: Added the Function Reference section.

2015-04-02T09:23:15Z

Added the Function Reference section.

← Older revision		Revision as of 09:23, 2 April 2015
Line 1:		Line 1:
	= Introduction =		== Introduction ==

	A memory pool is a block of memory that an application allocates for all its memory needs. The application draws from this pool rather than the system's free memory list whenever it requires memory.		A memory pool is a block of memory that an application allocates for all its memory needs. The application draws from this pool rather than the system's free memory list whenever it requires memory.
Line 11:		Line 11:
	If you know that your memory pool allocations will always be of the same size, prefer using an [[Exec_Item_Pools\|item pool]].		If you know that your memory pool allocations will always be of the same size, prefer using an [[Exec_Item_Pools\|item pool]].

	= Memory Pool Organization =		== Memory Pool Organization ==

	A memory pool consists of units called puddles. Other than that, it has no formal organization. There is no pool structure defined anywhere. All you know about a pool is its address. Exec's pool manager handles the rest of the details.		A memory pool consists of units called puddles. Other than that, it has no formal organization. There is no pool structure defined anywhere. All you know about a pool is its address. Exec's pool manager handles the rest of the details.
Line 25:		Line 25:
	The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.		The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.

	= Creating a Memory Pool =		== Creating a Memory Pool ==

	You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.		You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.
Line 51:		Line 51:
	Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!		Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

	= Allocating Memory from a Pool's Puddles =		== Allocating Memory from a Pool's Puddles ==

	Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.		Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.
Line 66:		Line 66:
	</syntaxhighlight>		</syntaxhighlight>

	= Freeing Memory from a Pool's Puddles =		== Freeing Memory from a Pool's Puddles ==

	An application can free a block of memory it allocated from a pool by calling FreePooled:		An application can free a block of memory it allocated from a pool by calling FreePooled():

	<syntaxhighlight>		<syntaxhighlight>
Line 74:		Line 74:
	</syntaxhighlight>		</syntaxhighlight>

	This function requires a pointer to the memory pool (mem_pool), a pointer to the block of memory being freed (mem_drop), and the size		This function requires a pointer to the memory pool (mem_pool), a pointer to the block of memory being freed (mem_drop), and the size of the memory being freed (mem_size).
	of the memory being freed (mem_size).

	= Deleting a Memory Pool =		== Deleting a Memory Pool ==

	A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.		A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.
Line 87:		Line 86:
	Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With FreeSysObject(), it would take only one call instead of many.		Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With FreeSysObject(), it would take only one call instead of many.

	= Concurrent Access =		== Concurrent Access ==

	Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.		Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.
Line 101:		Line 100:

	In this case, the memory is being shared between two Tasks or Processes so it must be of type MEMF_SHARED. By specifying that the memory pool is protected we are guaranteed all operations performed on the memory pool are thread safe.		In this case, the memory is being shared between two Tasks or Processes so it must be of type MEMF_SHARED. By specifying that the memory pool is protected we are guaranteed all operations performed on the memory pool are thread safe.

			== Function Reference ==

			The following table gives a brief description of the Exec functions that control memory pools. See the SDK/Autodocs for more details about each call.

			{\| class="wikitable"
			! Function
			! Description
			\|-
			\| AllocPooled()
			\| Allocate memory with the pool manager.
			\|-
			\| AllocSysObject(ASOT_MEMPOOL)
			\| Allocate and initialize a new memory pool.
			\|-
			\| AllocVecPooled()
			\| Allocate memory with the pool manager and track size.
			\|-
			\| FreePooled()
			\| Free pooled memory.
			\|-
			\| FreeSysObject(ASOT_MEMPOOL)
			\| Free a memory pool.
			\|-
			\| FreeVecPooled()
			\| Free pooled memory allocated with AllocVecPooled().
			\|}

			These Exec functions are now practically obsolete and not recommended for use in new code:

			{\| class="wikitable"
			! Function
			! Description
			\|-
			\| CreatePool()
			\| Use AllocSysObject(ASOT_MEMPOOL) instead.
			\|-
			\| DeletePool()
			\| Use FreeSysObject(ASOT_MEMPOOL) instead.
			\|}

Daniel Jedlicka: Added a reference and link to Item Pools.

2015-04-02T07:45:41Z

Added a reference and link to Item Pools.

← Older revision		Revision as of 07:45, 2 April 2015
Line 8:		Line 8:

	An application using a memory pool will have faster memory allocations because the memory list of a pool is smaller, and therefore easier to traverse than the memory list of the system memory. For deallocations, it's even faster because deleting the pool itself deletes all the individual allocations made from it instead of having to deallocate each piece that was allocated.		An application using a memory pool will have faster memory allocations because the memory list of a pool is smaller, and therefore easier to traverse than the memory list of the system memory. For deallocations, it's even faster because deleting the pool itself deletes all the individual allocations made from it instead of having to deallocate each piece that was allocated.

			If you know that your memory pool allocations will always be of the same size, prefer using an [[Exec_Item_Pools\|item pool]].

	= Memory Pool Organization =		= Memory Pool Organization =

Steven Solie: /* Deleting a Memory Pool */

2014-08-28T16:11:00Z

Deleting a Memory Pool

← Older revision		Revision as of 16:11, 28 August 2014
Line 83:		Line 83:
	</syntaxhighlight>		</syntaxhighlight>

	Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With ~~DeletePool~~(), it would take only one call instead of many.		Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With FreeSysObject(), it would take only one call instead of many.

	= Concurrent Access =		= Concurrent Access =

Steven Solie: /* Creating a Memory Pool */

2013-04-30T16:35:40Z

Creating a Memory Pool

← Older revision		Revision as of 16:35, 30 April 2013
Line 25:		Line 25:
	= Creating a Memory Pool =		= Creating a Memory Pool =

	You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.		You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.

	If successful, AllocSysObject() returns the address of the memory pool.		If successful, AllocSysObject() returns the address of the memory pool.

Steven Solie: /* Allocating Memory from a Pool's Puddles */

2013-04-30T16:33:38Z

Allocating Memory from a Pool's Puddles

← Older revision		Revision as of 16:33, 30 April 2013
Line 54:		Line 54:

	<syntaxhighlight>		<syntaxhighlight>
		⚫	struct Rectangle *rect = IExec->AllocPooled(mem_pool, sizeof(struct Rectangle);
	struct timerequest *TimerReq;

			if (rect != NULL)
⚫	if ~~(TimerReq~~ = IExec->AllocPooled(mem_pool, sizeof(struct ~~timerequest)~~)
	{		{
	// ...		// ...

Steven Solie: /* Creating a Memory Pool */

2013-04-30T16:28:42Z

Creating a Memory Pool

← Older revision		Revision as of 16:28, 30 April 2013
Line 25:		Line 25:
	= Creating a Memory Pool =		= Creating a Memory Pool =

	You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size, and memory type. The memory type is ~~borrowed~~ ~~from~~ ~~the~~ ~~AllocMem()~~ ~~function~~ ~~and~~ is ~~comprised~~ of ~~the~~ ~~MEMF_~~ ~~flags~~ ~~defined~~ in ~~<exec/memory.h>.~~ ~~See~~ ~~the~~ ~~Autodoc~~ ~~for~~ ~~AllocMem() for more information on those~~ ~~flags~~.		You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.

	If successful, AllocSysObject() returns the address of the memory pool.		If successful, AllocSysObject() returns the address of the memory pool.
Line 45:		Line 45:
	The example above attempts to create a pool of memory with a puddle size of 4096 bytes and a threshold size of 2048 bytes.		The example above attempts to create a pool of memory with a puddle size of 4096 bytes and a threshold size of 2048 bytes.

	If your application requires memory of different types (for example, ~~Private~~ memory and ~~Shared~~ memory), it must create a pool for each type.		If your application requires memory of different types (for example, private memory and shared memory), it must create a pool for each type.

	Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!		Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

Steven Solie at 16:25, 30 April 2013

2013-04-30T16:25:49Z

← Older revision		Revision as of 16:25, 30 April 2013
Line 85:		Line 85:
	Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With DeletePool(), it would take only one call instead of many.		Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With DeletePool(), it would take only one call instead of many.

			= Concurrent Access =
	= Why Use Pools When You Can Allocate Memory Yourself? =

			Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.
	With pools, you have the pool manager to handle all the details of allocating memory. You can sit back and create the pool, allocate memory from the puddles and free the pool when you're done. That's a lot easier than doing it yourself.

			<syntaxhighlight>
			APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
			ASOPOOL_MFlags, MEMF_SHARED,
			ASOPOOL_Puddle, 4096,
			ASOPOOL_Threshold, 2048,
			ASOPOOL_Protected, TRUE,
			TAG_END);
			</syntaxhighlight>

			In this case, the memory is being shared between two Tasks or Processes so it must be of type MEMF_SHARED. By specifying that the memory pool is protected we are guaranteed all operations performed on the memory pool are thread safe.