Exec Semaphores - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:17:07Z

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

← Older revision		Revision as of 19:17, 26 January 2025
Line 20:		Line 20:
	Exec semaphores are signal based. Using signal semaphores is the easiest way to protect shared, single-access resources in the Amiga. Your task will sleep until the semaphore is available for use. The SignalSemaphore structure is as follows:		Exec semaphores are signal based. Using signal semaphores is the easiest way to protect shared, single-access resources in the Amiga. Your task will sleep until the semaphore is available for use. The SignalSemaphore structure is as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SignalSemaphore {		struct SignalSemaphore {
	struct Node ss_Link;		struct Node ss_Link;
Line 51:		Line 51:
	A practical application of a SignalSemaphore would be to use it as the base of a shared data structure. For example:		A practical application of a SignalSemaphore would be to use it as the base of a shared data structure. For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SharedList {		struct SharedList {
	struct SignalSemaphore sl_Semaphore;		struct SignalSemaphore sl_Semaphore;
Line 68:		Line 68:
	To create and initialize a ''public'' semaphore for a data item and add it to the public semaphore list maintained by Exec, the following function should be used. (This will prevent the semaphore from being added or removed more than once by separate programs that use the semaphore).		To create and initialize a ''public'' semaphore for a data item and add it to the public semaphore list maintained by Exec, the following function should be used. (This will prevent the semaphore from being added or removed more than once by separate programs that use the semaphore).

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	CONST_STRPTR name; // name of semaphore to add		CONST_STRPTR name; // name of semaphore to add
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
Line 104:		Line 104:
	To obtain a semaphore use:		To obtain a semaphore use:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
	IExec->ObtainSemaphore(semaphore);		IExec->ObtainSemaphore(semaphore);
Line 111:		Line 111:
	To get an exclusive lock on a ''public'' semaphore, the following code should be used:		To get an exclusive lock on a ''public'' semaphore, the following code should be used:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	STRPTR name;		STRPTR name;
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
Line 129:		Line 129:
	To obtain a shared semaphore, use:		To obtain a shared semaphore, use:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
	IExec->ObtainSemaphoreShared(semaphore);		IExec->ObtainSemaphoreShared(semaphore);
Line 136:		Line 136:
	To obtain a ''public'' shared semaphore, the following code should be used:		To obtain a ''public'' shared semaphore, the following code should be used:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	STRPTR name;		STRPTR name;
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
Line 152:		Line 152:
	To attempt to obtain a semaphore, use the following:		To attempt to obtain a semaphore, use the following:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
	IExec->AttemptSemaphore(semaphore);		IExec->AttemptSemaphore(semaphore);
Line 159:		Line 159:
	To make an attempt to obtain a ''public'' semaphore, the following code should be used:		To make an attempt to obtain a ''public'' semaphore, the following code should be used:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	UBYTE *name;		UBYTE *name;
	struct SignalSemaphore *semaphore;		struct SignalSemaphore *semaphore;
Line 178:		Line 178:
	All of this can be accomplished with a single call to FreeSysObject():		All of this can be accomplished with a single call to FreeSysObject():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->FreeSysObject(ASOT_SEMAPHORE, semaphore);		IExec->FreeSysObject(ASOT_SEMAPHORE, semaphore);
	</syntaxhighlight>		</syntaxhighlight>
Line 192:		Line 192:
	For example:		For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->ObtainSemaphore((struct SignalSemaphore *)SemaphoreList);		IExec->ObtainSemaphore((struct SignalSemaphore *)SemaphoreList);
	IExec->ObtainSemaphoreList(SemaphoreList->sl_List);		IExec->ObtainSemaphoreList(SemaphoreList->sl_List);
Line 208:		Line 208:
	A simple "do nothing" example of Exec signal semaphore use is shown below. When the semaphore is owned by a task, attempted access by other tasks will block. A nesting count is maintained, so the current task can safely call ObtainSemaphore() on the same semaphore.		A simple "do nothing" example of Exec signal semaphore use is shown below. When the semaphore is owned by a task, attempted access by other tasks will block. A nesting count is maintained, so the current task can safely call ObtainSemaphore() on the same semaphore.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// semaphore.c - Exec semaphore example - compile with gcc -o semaphore semaphore.c		// semaphore.c - Exec semaphore example - compile with gcc -o semaphore semaphore.c
	#include <exec/types.h>		#include <exec/types.h>

Steven Solie: /* Obtaining a SignalSemaphore Exclusively */

2012-07-12T20:02:17Z

Obtaining a SignalSemaphore Exclusively

← Older revision		Revision as of 20:02, 12 July 2012
Line 100:		Line 100:
	The ObtainSemaphore() function can be used to get an exclusive lock on a semaphore. If another task currently has an exclusive or shared lock(s) on the semaphore, your task will be put to sleep until all locks on the the semaphore are released.		The ObtainSemaphore() function can be used to get an exclusive lock on a semaphore. If another task currently has an exclusive or shared lock(s) on the semaphore, your task will be put to sleep until all locks on the the semaphore are released.

		⚫	{{Note\|title=Semaphore Nesting\|text=SignalSemaphores have nesting. That is, if your task already owns the semaphore, it will get a second ownership of that semaphore. This simplifies the writing of routines that must own the semaphore but do not know if the caller has obtained it yet.}}
	{\| class="wikitable"
⚫	\| ''Semaphore Nesting~~.''~~ SignalSemaphores have nesting. That is, if your task already owns the semaphore, it will get a second ownership of that semaphore. This simplifies the writing of routines that must own the semaphore but do not know if the caller has obtained it yet.
	\|}

	To obtain a semaphore use:		To obtain a semaphore use:

Steven Solie: /* Exec Semaphores */

2012-05-23T20:43:41Z

Exec Semaphores

← Older revision		Revision as of 20:43, 23 May 2012
Line 13:		Line 13:
	# All tasks using shared data that is protected by a semaphore must ''always ask for the semaphore first before accessing the data''. If some task accesses the data directly without first going through the semaphore, the data may be corrupted. No task will have safe access to the data.		# All tasks using shared data that is protected by a semaphore must ''always ask for the semaphore first before accessing the data''. If some task accesses the data directly without first going through the semaphore, the data may be corrupted. No task will have safe access to the data.
	# A deadlock will occur if a task that owns an exclusive semaphore on some data inadvertently calls another task which tries to get an exclusive semaphore on that same data in blocking mode. Deadlocks and other such issues are beyond the scope of this manual. For more details on deadlocks and other problems of shared data in a multitasking system and the methods used to prevent them, refer to [http://en.wikipedia.org/wiki/Deadlock Wikipedia].		# A deadlock will occur if a task that owns an exclusive semaphore on some data inadvertently calls another task which tries to get an exclusive semaphore on that same data in blocking mode. Deadlocks and other such issues are beyond the scope of this manual. For more details on deadlocks and other problems of shared data in a multitasking system and the methods used to prevent them, refer to [http://en.wikipedia.org/wiki/Deadlock Wikipedia].

			[[Exec_Mutexes\|Mutexes]] are also provided by the operating system. A mutex is similar to an exclusive mode semaphore. Mutexes may are also optionally recursive (nested). The primary advantage of a mutex over an exclusive semaphore is that it will not use Forbid/Permit locking internally so the overall system will be less affected.

	== The Signal Semaphore ==		== The Signal Semaphore ==

Steven Solie: /* Function Reference */

2012-05-23T19:19:41Z

Function Reference

← Older revision		Revision as of 19:19, 23 May 2012
Line 243:		Line 243:
	\| AddSemaphore()		\| AddSemaphore()
	\| Initialize and add a signal semaphore to the system.		\| Initialize and add a signal semaphore to the system.
			\|-
			\| AllocSysObject(ASOT_SEMAPHORE)
			\| Allocate and initialize a new semaphore.
	\|-		\|-
	\| AttemptSemaphore()		\| AttemptSemaphore()
Line 249:		Line 252:
	\| FindSemaphore()		\| FindSemaphore()
	\| Find a given system signal semaphore.		\| Find a given system signal semaphore.
			\|-
			\| FreeSysObject(ASOT_SEMAPHORE)
			\| Free a semaphore.
	\|-		\|-
	\| InitSemaphore()		\| InitSemaphore()

Steven Solie: /* Semaphore Example */

2012-05-23T19:17:48Z

Semaphore Example

← Older revision		Revision as of 19:17, 23 May 2012
Line 214:		Line 214:
	#include <proto/exec.h>		#include <proto/exec.h>

	struct SignalSemaphore LockSemaphore ~~= {0}~~;		struct SignalSemaphore LockSemaphore;

	int main(int argc,char *argv[])		int main(int argc,char *argv[])
	{		{
			LockSemaphore = IExec->AllocSysObjectTags(ASOT_SEMAPHORE, TAG_END);
⚫	IExec->~~InitSemaphore~~(&LockSemaphore);

⚫	IExec->ObtainSemaphore(&LockSemaphore); // Task now owns the semaphore.
			if (LockSemaphore != NULL)
⚫	// ...
			{
⚫	IExec->ReleaseSemaphore(&LockSemaphore); // Task has released the semaphore.
		⚫	IExec->ObtainSemaphore(LockSemaphore); // Task now owns the semaphore.
		⚫	// ...
		⚫	IExec->ReleaseSemaphore(LockSemaphore); // Task has released the semaphore.

		⚫	IExec->FreeSysObject(ASOT_SEMPAHORE, LockSemaphore);
			}

	return 0;		return 0;
	}		}

Steven Solie: /* Removing a SignalSemaphore Structure */

2012-05-23T19:14:23Z

Removing a SignalSemaphore Structure

@@ Line 176: / Line 176: @@
 Semaphore resources can only be freed if the semaphore is not locked. A public semaphore should first be removed from the system semaphore list with the RemSemaphore() function. This prevents other tasks from finding the semaphore and trying to lock it. Once the semaphore is removed from the system list, the semaphore should be locked exclusively so no other task can lock it. Once the lock is obtained, it can be released again, and the resources can be deallocated.
 <syntaxhighlight>
 </syntaxhighlight>

Steven Solie: /* Making a SignalSemaphore Available to the Public */

2012-05-23T19:08:43Z

Making a SignalSemaphore Available to the Public

← Older revision		Revision as of 19:08, 23 May 2012
Line 62:		Line 62:
	=== Making a SignalSemaphore Available to the Public ===		=== Making a SignalSemaphore Available to the Public ===

	A semaphore should be used internally in your program if it has more than one task operating on shared data structures. There may also be cases when you wish to make a data item public to other applications but still need to restrict its access via semaphores. In that case, you would give your semaphore a unique name and add it to the public SignalSemaphore list maintained by Exec. The ~~AddSemaphore()~~ ~~function~~ ~~does~~ this for you.		A semaphore should be used internally in your program if it has more than one task operating on shared data structures. There may also be cases when you wish to make a data item public to other applications but still need to restrict its access via semaphores. In that case, you would give your semaphore a unique name and add it to the public SignalSemaphore list maintained by Exec. The ASOSEM_Name tag accomplishes this task for you.

	To create and initialize a ''public'' semaphore for a data item and add it to the public semaphore list maintained by Exec, the following function should be used. (This will prevent the semaphore from being added or removed more than once by separate programs that use the semaphore).		To create and initialize a ''public'' semaphore for a data item and add it to the public semaphore list maintained by Exec, the following function should be used. (This will prevent the semaphore from being added or removed more than once by separate programs that use the semaphore).

	<syntaxhighlight>		<syntaxhighlight>
	~~STRPTR~~ name; /* name of semaphore to add */		CONST_STRPTR name; // name of semaphore to add
	struct SignalSemaphore *~~sema~~;		struct SignalSemaphore *semaphore;

	IExec->Forbid();		IExec->Forbid();
	/* Make sure the semaphore name is unique */		// Make sure the semaphore name is unique
	if (!IExec->FindSemaphore(name)) {		if (!IExec->FindSemaphore(name)) {
	/* Allocate memory for the structure */		// Allocate memory for the structure
		⚫	// Note that the string 'name' is not copied. If that is needed, add
	sema = IExec->AllocVecTags(sizeof(struct SignalSemaphore),
			// ASOSEM_CopyName, TRUE to the tag list.
	AVT_Type, MEMF_SHARED,

	AVT_ClearWithValue, 0,
			semaphore = IExec->AllocSysObjectTags(ASOT_SEMAPHORE,
			ASOSEM_Name, name,
		⚫	ASOSEM_Pri, 0, /* Set the priority to zero */
	TAG_END);		TAG_END);

	if (~~sema~~ != NULL)		if (semaphore != NULL)
	{		{
			// Use the sempahore.
⚫	~~sema->ss_Link.ln_Pri =~~ 0; /* Set the priority to zero */
	sema->ss_Link.ln_Name = name;
⚫	/* Note that the string 'name' is not copied. If that is needed, ~~allocate memory */~~
	/* for it and copy the string. And add the semaphore the the system list */
	IExec->AddSemaphore(sema);
	}		}
	}		}

Steven Solie: /* Creating a SignalSemaphore Structure */

2012-05-23T18:57:13Z

Creating a SignalSemaphore Structure

@@ Line 58: / Line 58: @@
 === Creating a SignalSemaphore Structure ===
-To create a SignalSemaphore structure use the AllocSysObject() function with an object type of ASOT_SEMAPHORE.
+To create a SignalSemaphore structure use the AllocSysObject() function with an object type of ASOT_SEMAPHORE. Various tags control the attributes of the SignalSemaphore as explained in the autodoc.
 === Making a SignalSemaphore Available to the Public ===

Steven Solie: /* Creating a SignalSemaphore Structure */

2012-05-23T18:56:19Z

Creating a SignalSemaphore Structure

@@ Line 58: / Line 58: @@
 === Creating a SignalSemaphore Structure ===
-To initialize a SignalSemaphore structure use the InitSemaphore() function. This function initializes the list structure and the nesting and queue counters. It does not change the semaphore's name or priority fields.
+To create a SignalSemaphore structure use the AllocSysObject() function with an object type of ASOT_SEMAPHORE.
 This fragment creates and initializes a semaphore for a data item such as the SharedList structure above.

Steven Solie: /* Exec Semaphores */

2012-05-23T18:45:44Z

Exec Semaphores

← Older revision		Revision as of 18:45, 23 May 2012
Line 1:		Line 1:
	== Exec Semaphores ==		== Exec Semaphores ==

	Semaphores are a feature of Exec which provide a general method for tasks to arbitrate for the use of memory or other system resources they may be sharing. This ~~chapter~~ describes the structure of Exec semaphores and the various support functions provided for their use. Since the semaphore system uses Exec lists and signals, some familiarity with these concepts is helpful for understanding semaphores.		Semaphores are a feature of Exec which provide a general method for tasks to arbitrate for the use of memory or other system resources they may be sharing. This section describes the structure of Exec semaphores and the various support functions provided for their use. Since the semaphore system uses Exec lists and signals, some familiarity with these concepts is helpful for understanding semaphores.

	In any multitasking or multi-processing system there is a need to share data among independently executing tasks. If the data is static (that is, it never changes), then there is no problem. However, if the data is variable, then there must be some way for a task that is about to make a change to keep other tasks from looking at the data.		In any multitasking or multi-processing system there is a need to share data among independently executing tasks. If the data is static (that is, it never changes), then there is no problem. However, if the data is variable, then there must be some way for a task that is about to make a change to keep other tasks from looking at the data.
Line 12:		Line 12:

	# All tasks using shared data that is protected by a semaphore must ''always ask for the semaphore first before accessing the data''. If some task accesses the data directly without first going through the semaphore, the data may be corrupted. No task will have safe access to the data.		# All tasks using shared data that is protected by a semaphore must ''always ask for the semaphore first before accessing the data''. If some task accesses the data directly without first going through the semaphore, the data may be corrupted. No task will have safe access to the data.
	# A deadlock will occur if a task that owns an exclusive semaphore on some data inadvertently calls another task which tries to get an exclusive semaphore on that same data in blocking mode. Deadlocks and other such issues are beyond the scope of this manual. For more details on deadlocks and other problems of shared data in a multitasking system and the methods used to prevent them, refer to a ~~textbook in computer science such as ''Operating Systems'' by Tannenbaum (Prentice-Hall)~~.		# A deadlock will occur if a task that owns an exclusive semaphore on some data inadvertently calls another task which tries to get an exclusive semaphore on that same data in blocking mode. Deadlocks and other such issues are beyond the scope of this manual. For more details on deadlocks and other problems of shared data in a multitasking system and the methods used to prevent them, refer to [http://en.wikipedia.org/wiki/Deadlock Wikipedia].

	== The Signal Semaphore ==		== The Signal Semaphore ==