Exec Named Memory - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:09:27Z

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

← Older revision		Revision as of 19:09, 26 January 2025
Line 9:		Line 9:
	Named memory is first created using the AllocNamedMemory() function:		Named memory is first created using the AllocNamedMemory() function:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MySharedData {		struct MySharedData {
	uint32 value;		uint32 value;
Line 34:		Line 34:
	In order to read from or write to the named memory, a Task or Process must first lock it. Here is an example of an exclusive lock which will block the caller. If some other entity has a lock on the data it will block the caller until that lock is released.		In order to read from or write to the named memory, a Task or Process must first lock it. Here is an example of an exclusive lock which will block the caller. If some other entity has a lock on the data it will block the caller until that lock is released.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MySharedData *data = IExec->LockNamedMemory(NULL, "MySharedData");		struct MySharedData *data = IExec->LockNamedMemory(NULL, "MySharedData");

Line 50:		Line 50:
	Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.		Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MySharedData *data = IExec->AttemptNamedMemory(NULL, "MySharedData");		struct MySharedData *data = IExec->AttemptNamedMemory(NULL, "MySharedData");

Line 61:		Line 61:
	In either case, when a lock succeeds the caller (and only the caller) must unlock it when finished. This ensures the next Task or Process can access the data. Be careful to call UnlockNamedMemory() on the same context as you called LockNamedMemory() or AttemptNamedMemory().		In either case, when a lock succeeds the caller (and only the caller) must unlock it when finished. This ensures the next Task or Process can access the data. Be careful to call UnlockNamedMemory() on the same context as you called LockNamedMemory() or AttemptNamedMemory().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->UnlockNamedMemory(NULL, "MySharedData");		IExec->UnlockNamedMemory(NULL, "MySharedData");
	</syntaxhighlight>		</syntaxhighlight>
Line 77:		Line 77:
	The ScanNamedMemory() function is used to discover what named memory blocks are available. ScanNamedMemory() may also be used to scan just the namespaces.		The ScanNamedMemory() function is used to discover what named memory blocks are available. ScanNamedMemory() may also be used to scan just the namespaces.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 myMemScanHook(struct Hook hook, APTR userdata, struct SNMMessage scanMsg)		uint32 myMemScanHook(struct Hook hook, APTR userdata, struct SNMMessage scanMsg)
	{		{
Line 97:		Line 97:
	Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory but it is advisable to follow some kind of protocol regardless.		Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory but it is advisable to follow some kind of protocol regardless.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL success = IExec->FreeNamedMemory(NULL, "MySharedData");		BOOL success = IExec->FreeNamedMemory(NULL, "MySharedData");

Daniel Jedlicka: Added the Function Reference section.

2015-04-02T11:22:08Z

Added the Function Reference section.

← Older revision		Revision as of 11:22, 2 April 2015
Line 1:		Line 1:
	= Introduction =		== Introduction ==

	In a multi-tasking environment, it is often desirable to be able to share resources between two more more different Tasks or Processes. This can be done by passing memory pointers, but this is difficult since there is no defined "protocol" for this.		In a multi-tasking environment, it is often desirable to be able to share resources between two more more different [[Exec Tasks\|Tasks]] or Processes. This can be done by passing memory pointers, but this is difficult since there is no defined "protocol" for this.

	Exec V51 introduces a new concept called named memory. Instead of having to pass a pointer around, you decide on a name for your memory and have others (or yourself) access this memory by ~~it's~~ name. In addition, named memory can be organized into different namespaces. This allows for the same name to exist in different namespaces. All names in the same namespace must be unique.		Exec V51 introduces a new concept called ''named memory''. Instead of having to pass a pointer around, you decide on a name for your memory and have others (or yourself) access this memory by its name. In addition, named memory can be organized into different namespaces. This allows for the same name to exist in different namespaces. All names in the same namespace must be unique.

	= Creating Named Memory =		== Creating Named Memory ==

	Named memory is first created using the AllocNamedMemory() function.		Named memory is first created using the AllocNamedMemory() function:

	<syntaxhighlight>		<syntaxhighlight>
Line 28:		Line 28:
	In this example, the global namespace is being used and the name of the memory is ''MySharedData''.		In this example, the global namespace is being used and the name of the memory is ''MySharedData''.

	= Sharing Named Memory =		== Sharing Named Memory ==

	Named memory is meant to be shared between two or more Tasks or Processes. As such, a strict protocol must be obeyed to ensure the shared data remains consistent.		Named memory is meant to be shared between two or more Tasks or Processes. As such, a strict protocol must be obeyed to ensure the shared data remains consistent.

	In order to read or write to the named memory, a Task or Process must first lock it. Here is an example of an exclusive lock which will block the caller. If some other entity has a lock on the data it will block the caller until that lock is released.		In order to read from or write to the named memory, a Task or Process must first lock it. Here is an example of an exclusive lock which will block the caller. If some other entity has a lock on the data it will block the caller until that lock is released.

	<syntaxhighlight>		<syntaxhighlight>
Line 46:		Line 46:
	</syntaxhighlight>		</syntaxhighlight>

	Named memory may disappear at any time so there is no guarantee that a call to LockNamedMemory() will succeed. Keep this in mind when designing your applications.		Named memory may disappear at any time so there is no guarantee that a call to LockNamedMemory() will succeed. Keep this in mind when designing your applications!

	Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.		Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.
Line 65:		Line 65:
	</syntaxhighlight>		</syntaxhighlight>

	= The "resident" Namespace =		== The "resident" Namespace ==

	One namespace is predefined with a special functionality: ''resident''. This namespace and ~~it's~~ objects will be restored after reboot through ColdStart().		One namespace is predefined with a special functionality: ''resident''. This namespace and its objects will be restored after reboot through ColdStart().

	To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.		To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.
Line 93:		Line 93:
	</syntaxhighlight>		</syntaxhighlight>

	= Freeing Named Memory =		== Freeing Named Memory ==

	Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory but it is advisable to follow some kind of protocol regardless.		Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory but it is advisable to follow some kind of protocol regardless.
Line 105:		Line 105:

	The boolean return value needs to be checked to verify whether the memory is now free or not. It is possible another Task or Process has a lock on the named memory at the same time it is being freed. This is why it is so important to establish a protocol when using shared memory.		The boolean return value needs to be checked to verify whether the memory is now free or not. It is possible another Task or Process has a lock on the named memory at the same time it is being freed. This is why it is so important to establish a protocol when using shared memory.

			== Function Reference ==

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

			{\| class="wikitable"
			! Function
			! Description
			\|-
			\| AllocNamedMemory()
			\| Allocate a named memory object.
			\|-
			\| AttemptNamedMemory()
			\| Try to obtain access to named memory.
			\|-
			\| FindNamedMemory()
			\| Search for a named memory object.
			\|-
			\| FreeNamedMemory()
			\| Free a named memory object.
			\|-
			\| LockNamedMemory()
			\| Lock a named memory object for exclusive access.
			\|-
			\| ScanNamedMemory()
			\| Scan through existing named memory objects and/or namespaces.
			\|-
			\| UnlockNamedMemory()
			\| Unlock a named memory object.
			\|-
			\| UpdateNamedMemory()
			\| Recalculate the checksum for a named memory object.
			\|}

Steven Solie: /* To be documented */

2013-04-30T21:42:46Z

To be documented

← Older revision		Revision as of 21:42, 30 April 2013
Line 105:		Line 105:

	The boolean return value needs to be checked to verify whether the memory is now free or not. It is possible another Task or Process has a lock on the named memory at the same time it is being freed. This is why it is so important to establish a protocol when using shared memory.		The boolean return value needs to be checked to verify whether the memory is now free or not. It is possible another Task or Process has a lock on the named memory at the same time it is being freed. This is why it is so important to establish a protocol when using shared memory.

	= To be documented =

	<syntaxhighlight>
	FindNamedMemory()
	UpdateNamedMemory()
	ScanNamedMemory()
	</syntaxhighlight>

Steven Solie: /* The "resident" Namespace */

2013-04-30T21:42:35Z

The "resident" Namespace

← Older revision		Revision as of 21:42, 30 April 2013
Line 70:		Line 70:

	To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.		To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.

			The checksum may also be recalculated explicitly by using the UpdateNamedMemory() function. This may be needed in cases where the data initially failed the checksum.

	The FindNamedMemory() function is used to access resident blocks of memory if you already know the name of the block.		The FindNamedMemory() function is used to access resident blocks of memory if you already know the name of the block.

	The ScanNamedMemory() function is used to discover what named memory blocks are available. ScanNamedMemory() may also be used to scan just the namespaces ~~as well~~.		The ScanNamedMemory() function is used to discover what named memory blocks are available. ScanNamedMemory() may also be used to scan just the namespaces.

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* The "resident" Namespace */

2013-04-30T21:37:57Z

The "resident" Namespace

← Older revision		Revision as of 21:37, 30 April 2013
Line 70:		Line 70:

	To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.		To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.

			The FindNamedMemory() function is used to access resident blocks of memory if you already know the name of the block.

			The ScanNamedMemory() function is used to discover what named memory blocks are available. ScanNamedMemory() may also be used to scan just the namespaces as well.

			<syntaxhighlight>
			uint32 myMemScanHook(struct Hook hook, APTR userdata, struct SNMMessage scanMsg)
			{
			IDOS->Printf("Object %s in namespace %s at address %p\n",
			scanMsg->Name, scanMsg->Namespace, scanMsg->Memory);

			return 0;
			}

			struct Hook *scanHook = IExec->AllocSysObjectTags(ASOT_HOOK,
			ASOHOOK_Entry, myMemScanHook,
			TAG_END);

			uint32 result = IExec->ScanNamedMemory(scanHook, 0, NULL);
			</syntaxhighlight>

	= Freeing Named Memory =		= Freeing Named Memory =

Steven Solie: /* Freeing Named Memory */

2013-04-30T21:28:46Z

Freeing Named Memory

← Older revision		Revision as of 21:28, 30 April 2013
Line 73:		Line 73:
	= Freeing Named Memory =		= Freeing Named Memory =

	Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory ~~although~~ it is advisable to ~~have~~ ~~the~~ ~~same~~ ~~entity~~ ~~free~~ ~~it that created it~~.		Named memory should be freed when no longer in use. Any Task or Process may attempt to free named memory but it is advisable to follow some kind of protocol regardless.

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Sharing Named Memory */

2013-04-30T21:21:55Z

Sharing Named Memory

← Older revision		Revision as of 21:21, 30 April 2013
Line 45:		Line 45:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			Named memory may disappear at any time so there is no guarantee that a call to LockNamedMemory() will succeed. Keep this in mind when designing your applications.

	Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.		Sometimes it is not appropriate to block the caller if the shared data is not available. Here is an example of an exclusive lock which does not block the caller.

Steven Solie at 21:20, 30 April 2013

2013-04-30T21:20:13Z

← Older revision		Revision as of 21:20, 30 April 2013
Line 4:		Line 4:

	Exec V51 introduces a new concept called named memory. Instead of having to pass a pointer around, you decide on a name for your memory and have others (or yourself) access this memory by it's name. In addition, named memory can be organized into different namespaces. This allows for the same name to exist in different namespaces. All names in the same namespace must be unique.		Exec V51 introduces a new concept called named memory. Instead of having to pass a pointer around, you decide on a name for your memory and have others (or yourself) access this memory by it's name. In addition, named memory can be organized into different namespaces. This allows for the same name to exist in different namespaces. All names in the same namespace must be unique.

⚫	= The "resident" Namespace =

⚫	One namespace is predefined with a special functionality: ''resident''. This namespace and it's objects will be restored after reboot through ColdStart().

⚫	To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.

	= Creating Named Memory =		= Creating Named Memory =
Line 68:		Line 62:
	IExec->UnlockNamedMemory(NULL, "MySharedData");		IExec->UnlockNamedMemory(NULL, "MySharedData");
	</syntaxhighlight>		</syntaxhighlight>

		⚫	= The "resident" Namespace =

		⚫	One namespace is predefined with a special functionality: ''resident''. This namespace and it's objects will be restored after reboot through ColdStart().

		⚫	To ensure data integrity, it is possible to have the memory block automatically checksummed. The checksum is validated after reboot. If checksumming is enabled and the stored checksum and newly computed checksums match, the block is available to subsequent FindNamedMemory() calls. Otherwise, the block is discarded. If no checksumming is enabled for the block, the application must ensure data integrity.

	= Freeing Named Memory =		= Freeing Named Memory =

Steven Solie at 21:13, 30 April 2013

2013-04-30T21:13:13Z

@@ Line 35: / Line 35: @@
 = Sharing Named Memory =
 = Freeing Named Memory =
@@ Line 52: / Line 85: @@
 <syntaxhighlight>
 FindNamedMemory()
 ScanNamedMemory()
 </syntaxhighlight>

Steven Solie: /* Freeing Named Memory */

2013-04-30T19:26:37Z

Freeing Named Memory

← Older revision		Revision as of 19:26, 30 April 2013
Line 33:		Line 33:

	In this example, the global namespace is being used and the name of the memory is ''MySharedData''.		In this example, the global namespace is being used and the name of the memory is ''MySharedData''.

			= Sharing Named Memory =

	= Freeing Named Memory =		= Freeing Named Memory =