Exec Item Pools - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:20:43Z

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

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

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,		APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
	ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,		ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,
Line 43:		Line 43:
	Here is an example with garbage collection disabled and the maximum number of items set to 2000. This kind of item pool would allocate items very quickly with an upper bound so that it will not eat too much memory.		Here is an example with garbage collection disabled and the maximum number of items set to 2000. This kind of item pool would allocate items very quickly with an upper bound so that it will not eat too much memory.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,		APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
	ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,		ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,
Line 56:		Line 56:
	The second example defines the ITEMGC_AFTERCOUNT policy for the item pool. With this policy in place, garbage collection will automatically be performed after a given number of items have been deallocated. This number is specified via the ASOITEM_GCParameter tag:		The second example defines the ITEMGC_AFTERCOUNT policy for the item pool. With this policy in place, garbage collection will automatically be performed after a given number of items have been deallocated. This number is specified via the ASOITEM_GCParameter tag:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,		APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
	ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,		ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,
Line 70:		Line 70:
	Memory is obtained from an item pool by calling ItemPoolAlloc(). ItemPoolAlloc() requires only a pointer to the item pool and nothing more. That is because the size of every item is exactly the same as defined by the ASOITEM_ItemSize tag during pool creation. If successful, ItemPoolAlloc() returns a pointer to the memory.		Memory is obtained from an item pool by calling ItemPoolAlloc(). ItemPoolAlloc() requires only a pointer to the item pool and nothing more. That is because the size of every item is exactly the same as defined by the ASOITEM_ItemSize tag during pool creation. If successful, ItemPoolAlloc() returns a pointer to the memory.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Rectangle rect = (struct Rectangle) IExec->ItemPoolAlloc(item_pool);		struct Rectangle rect = (struct Rectangle) IExec->ItemPoolAlloc(item_pool);

Line 91:		Line 91:
	Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.		Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->ItemPoolFree(item_pool, rect);		IExec->ItemPoolFree(item_pool, rect);
	</syntaxhighlight>		</syntaxhighlight>
Line 105:		Line 105:
	Explicit flushing on an item pool is possible without actually deleting the item pool by using the ItemPoolFlush() function. In this example, the item pool will have all its items freed.		Explicit flushing on an item pool is possible without actually deleting the item pool by using the ItemPoolFlush() function. In this example, the item pool will have all its items freed.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->ItemPoolFlush(item_pool);		IExec->ItemPoolFlush(item_pool);
	</syntaxhighlight>		</syntaxhighlight>
Line 114:		Line 114:
	* item contructor and destructor (ASOITEM_Constructor and ASOITEM_Destructor)		* item contructor and destructor (ASOITEM_Constructor and ASOITEM_Destructor)

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 num_set = IExec->ItemPoolControl(item_pool,		uint32 num_set = IExec->ItemPoolControl(item_pool,
	ASOITEM_GCPolicy, ITEMGC_AFTERCOUNT,		ASOITEM_GCPolicy, ITEMGC_AFTERCOUNT,
Line 130:		Line 130:
	Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.		Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,		APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
	ASOITEM_MFlags, MEMF_SHARED,		ASOITEM_MFlags, MEMF_SHARED,

Daniel Jedlicka: Added a code example for the ITEMGC_AFTERCOUNT policy. Added the Function Reference section.

2015-04-02T08:43:51Z

Added a code example for the ITEMGC_AFTERCOUNT policy. Added the Function Reference section.

← Older revision		Revision as of 08:43, 2 April 2015
Line 1:		Line 1:
	= Introduction =		== Introduction ==

	An item pool is a special memory pool that can only allocate and deallocate predefined slabs of memory. Every allocation from this pool is exactly the same size. ~~There~~ are no exceptions to this rule. Allocation and deallocation of these items is typically extremely fast unless the pool needs to be enlarged or garbage collection takes place. Item pools are commonly called "slab allocators" although the latter usually also refers to a kind of allocation that leaves data intact between calls.		An item pool is a special [[Exec Memory Pools\|memory pool]] that can only allocate and deallocate predefined slabs of memory. Every allocation from this pool is exactly the same size; there are no exceptions to this rule. Allocation and deallocation of these items is typically extremely fast unless the pool needs to be enlarged or garbage collection takes place. Item pools are commonly called "slab allocators" although the latter usually also refers to a kind of allocation that leaves data intact between calls.

	An item pool should be used whenever an application wants to allocate a large number of equally sized objects. For example, an application allocating a couple thousand Rectangle structures, or list items, could use an item pool for that to dramatically reduce the allocation time and memory fragmentation.		An item pool should be used whenever an application wants to allocate a large number of equally sized objects. For example, an application allocating a couple thousand Rectangle structures, or list items, could use an item pool for that to dramatically reduce the allocation time and memory fragmentation.
Line 7:		Line 7:
	Many applications frequently allocate very similar pieces of memory, like list nodes, rectangles, or similar structures. If these items are sufficiently large, their constant allocation and deallocation will produce a potentially large amount of fragmented memory nodes.		Many applications frequently allocate very similar pieces of memory, like list nodes, rectangles, or similar structures. If these items are sufficiently large, their constant allocation and deallocation will produce a potentially large amount of fragmented memory nodes.

	= Creating an Item Pool =		== Creating an Item Pool ==

	You create an item pool by calling AllocSysObject() with the ASOT_ITEMPOOL object type and the item size, memory type, garbage collection policy and other options.		You create an item pool by calling AllocSysObject() with the ASOT_ITEMPOOL object type and the item size, memory type, garbage collection policy and other options.
Line 37:		Line 37:
	Take note that all you know about an item pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!		Take note that all you know about an item pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

	== Garbage Collection Policy ==		=== Garbage Collection Policy ===

	Each item pool has a garbage collection policy associated with it. ~~The~~ garbage collection policy can have a negative impact on the allocation/deallocation speed of an item pool so it is important to choose the policy which is best for your specific application.		Each item pool has a garbage collection policy associated with it. Note that the garbage collection policy can have a negative impact on the allocation/deallocation speed of an item pool, so it is important to choose the policy which is best for your specific application.

	Here is an example with garbage collection disabled and the maximum number of items set to 2000. This kind of item pool would allocate items very quickly with an upper bound so that it will not eat too much memory.		Here is an example with garbage collection disabled and the maximum number of items set to 2000. This kind of item pool would allocate items very quickly with an upper bound so that it will not eat too much memory.
Line 54:		Line 54:
	In this case, the application is responsible for manually performing garbage collection using the ItemPoolGC() function.		In this case, the application is responsible for manually performing garbage collection using the ItemPoolGC() function.

			The second example defines the ITEMGC_AFTERCOUNT policy for the item pool. With this policy in place, garbage collection will automatically be performed after a given number of items have been deallocated. This number is specified via the ASOITEM_GCParameter tag:
⚫	= Allocating Memory from an Item Pool =

			<syntaxhighlight>
			APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
			ASOITEM_MFlags, MEMF_PRIVATE \| MEMF_CLEAR,
			ASOITEM_ItemSize, sizeof(struct Rectangle),
			ASOITEM_MaxSize, 2000,
			ASOITEM_GCPolicy, ITEMGC_AFTERCOUNT, /* perform garbage collection */
			ASOITEM_GCParameter, 500, /* after 500 items have been deallocated */
			TAG_END);
			</syntaxhighlight>

		⚫	== Allocating Memory from an Item Pool ==

	Memory is obtained from an item pool by calling ItemPoolAlloc(). ItemPoolAlloc() requires only a pointer to the item pool and nothing more. That is because the size of every item is exactly the same as defined by the ASOITEM_ItemSize tag during pool creation. If successful, ItemPoolAlloc() returns a pointer to the memory.		Memory is obtained from an item pool by calling ItemPoolAlloc(). ItemPoolAlloc() requires only a pointer to the item pool and nothing more. That is because the size of every item is exactly the same as defined by the ASOITEM_ItemSize tag during pool creation. If successful, ItemPoolAlloc() returns a pointer to the memory.
Line 75:		Line 87:
	The optional item constructor, specified with the ASOITEM_Constructor tag, is called immediately after an item is successfully allocated. If the MEMF_CLEAR was specified, the item will have been cleared before the constructor is called.		The optional item constructor, specified with the ASOITEM_Constructor tag, is called immediately after an item is successfully allocated. If the MEMF_CLEAR was specified, the item will have been cleared before the constructor is called.

	= Freeing Memory from an Item Pool =		== Freeing Memory from an Item Pool ==

	Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.		Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.
Line 87:		Line 99:
	The optional item destructor, specified with the ASOITEM_Destructor tag, is called immediately before an item is freed.		The optional item destructor, specified with the ASOITEM_Destructor tag, is called immediately before an item is freed.

	= Controlling an Item Pool =		== Controlling an Item Pool ==

	The application programmer can exercise more control of an item pool than is possible with the more generic [[Exec_Memory_Pools\|Memory Pools]].		The application programmer can exercise more control of an item pool than is possible with the more generic [[Exec_Memory_Pools\|Memory Pools]].
Line 99:		Line 111:
	It may also be desirable to change certain item pool behavior as an application continues to execute. The ItemPoolControl() function may be used to alter the:		It may also be desirable to change certain item pool behavior as an application continues to execute. The ItemPoolControl() function may be used to alter the:
	* maximum number of items (ASOITEM_MaxSize)		* maximum number of items (ASOITEM_MaxSize)
	* garbage collection policy (ASOITEM_GCPolicy and ~~ASOITEM_GCParam~~)		* garbage collection policy (ASOITEM_GCPolicy and ASOITEM_GCParameter)
	* item contructor and destructor (ASOITEM_Constructor and ASOITEM_Destructor)		* item contructor and destructor (ASOITEM_Constructor and ASOITEM_Destructor)

Line 114:		Line 126:
	In this example, the garbage collection policy and maximum number of items allowed in the item pool are being changed.		In this example, the garbage collection policy and maximum number of items allowed in the item pool are being changed.

	= Concurrent Access =		== Concurrent Access ==

	Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.		Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.
Line 127:		Line 139:

	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 item pool is protected we are guaranteed all operations performed on the item 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 item pool is protected we are guaranteed all operations performed on the item pool are thread safe.

			== Function Reference ==

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

			{\| class="wikitable"
			! Function
			! Description
			\|-
			\| ItemPoolAlloc()
			\| Allocate an item from a pool.
			\|-
			\| ItemPoolControl()
			\| Control attributes in an item pool.
			\|-
			\| ItemPoolFlush()
			\| Delete all items in an item pool.
			\|-
			\| ItemPoolFree()
			\| Return an item to its pool for reuse.
			\|-
			\| ItemPoolGC()
			\| Perform garbage collection in an item pool.
			\|}

Steven Solie: /* Allocating Memory from an Item Pool */

2013-05-02T14:37:13Z

Allocating Memory from an Item Pool

← Older revision		Revision as of 14:37, 2 May 2013
Line 59:		Line 59:

	<syntaxhighlight>		<syntaxhighlight>
	struct Rectangle *rect = IExec->ItemPoolAlloc(item_pool);		struct Rectangle rect = (struct Rectangle) IExec->ItemPoolAlloc(item_pool);

	if (rect != NULL)		if (rect != NULL)

Steven Solie: /* Allocating Memory from an Item Pool */

2013-04-30T16:34:16Z

Allocating Memory from an Item Pool

← Older revision		Revision as of 16:34, 30 April 2013
Line 59:		Line 59:

	<syntaxhighlight>		<syntaxhighlight>
	struct Rectangle *rect;		struct Rectangle *rect = IExec->ItemPoolAlloc(item_pool);

	if (rect = ~~IExec->ItemPoolAlloc(item_pool)~~)		if (rect != NULL)
	{		{
	// ...		// ...

Steven Solie at 16:22, 30 April 2013

2013-04-30T16:22:46Z

← Older revision		Revision as of 16:22, 30 April 2013
Line 117:		Line 117:

	Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.		Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.

			<syntaxhighlight>
			APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
			ASOITEM_MFlags, MEMF_SHARED,
			ASOITEM_ItemSize, sizeof(struct Rectangle),
			ASOITEM_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 item pool is protected we are guaranteed all operations performed on the item pool are thread safe.

Steven Solie: /* Controlling an Item Pool */

2013-04-30T16:19:47Z

Controlling an Item Pool

← Older revision		Revision as of 16:19, 30 April 2013
Line 113:		Line 113:

	In this example, the garbage collection policy and maximum number of items allowed in the item pool are being changed.		In this example, the garbage collection policy and maximum number of items allowed in the item pool are being changed.

			= Concurrent Access =

			Item pools may be protected from concurrent access by specifying the ASOITEM_Protected tag when creating the pool.

Steven Solie: /* Deleting an Item Pool */

2013-04-30T16:17:33Z

Deleting an Item Pool

@@ Line 87: / Line 87: @@
 The optional item destructor, specified with the ASOITEM_Destructor tag, is called immediately before an item is freed.
-= Deleting an Item Pool =
+= Controlling an Item Pool =
 <syntaxhighlight>
-IExec->FreeSysObject(ASOT_ITEMPOOL, item_pool);
+IExec->ItemPoolFlush(item_pool);
 </syntaxhighlight>

Steven Solie: /* Deleting an Item Pool */

2013-04-30T16:00:31Z

Deleting an Item Pool

← Older revision		Revision as of 16:00, 30 April 2013
Line 89:		Line 89:
	= Deleting an Item Pool =		= Deleting an Item Pool =

	Similar to [[Exec_Memory_Pools\|Exec Memory Pools]], all memory allocated in the item pool is delete as soon as the item pool itself is freed ~~(via a call to FreeSysObject())~~.		Similar to [[Exec_Memory_Pools\|Exec Memory Pools]], all memory allocated in the item pool is delete as soon as the item pool itself is freed.

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Deleting an Item Pool */

2013-04-30T16:00:17Z

Deleting an Item Pool

← Older revision		Revision as of 16:00, 30 April 2013
Line 89:		Line 89:
	= Deleting an Item Pool =		= Deleting an Item Pool =

	Similar to ~~old~~ ~~exec~~ ~~memory pools~~, all memory allocated in the item pool is delete as soon as the item pool itself is freed (via a call to FreeSysObject).		Similar to [[Exec_Memory_Pools\|Exec Memory Pools]], all memory allocated in the item pool is delete as soon as the item pool itself is freed (via a call to FreeSysObject()).

			<syntaxhighlight>
			IExec->FreeSysObject(ASOT_ITEMPOOL, item_pool);
			</syntaxhighlight>

Steven Solie: /* Allocating Memory from an Item Pool */

2013-04-30T15:58:23Z

Allocating Memory from an Item Pool

← Older revision		Revision as of 15:58, 30 April 2013
Line 74:		Line 74:

	The optional item constructor, specified with the ASOITEM_Constructor tag, is called immediately after an item is successfully allocated. If the MEMF_CLEAR was specified, the item will have been cleared before the constructor is called.		The optional item constructor, specified with the ASOITEM_Constructor tag, is called immediately after an item is successfully allocated. If the MEMF_CLEAR was specified, the item will have been cleared before the constructor is called.

			= Freeing Memory from an Item Pool =

			Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.

			<syntaxhighlight>
			IExec->ItemPoolFree(item_pool, rect);
			</syntaxhighlight>

			In this example, the "rect" pointer must point to an item which was previously allocated with ItemPoolAlloc(). Items can never be reused or otherwise referenced after being freed.

			The optional item destructor, specified with the ASOITEM_Destructor tag, is called immediately before an item is freed.

	= Deleting an Item Pool =		= Deleting an Item Pool =