Exec Tasks - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:08:28Z

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

← Older revision		Revision as of 19:08, 26 January 2025
Line 10:		Line 10:
	Exec maintains task context and state information in a task-control data structure. Like most Exec structures, Task structures are dynamically linked onto various task queues through the use of an embedded Exec list Node structure (see [[Exec Lists and Queues]]). Any task can find its own task structure by calling FindTask(NULL). The C-language form of this structure is defined in the <exec/tasks.h> include file:		Exec maintains task context and state information in a task-control data structure. Like most Exec structures, Task structures are dynamically linked onto various task queues through the use of an embedded Exec list Node structure (see [[Exec Lists and Queues]]). Any task can find its own task structure by calling FindTask(NULL). The C-language form of this structure is defined in the <exec/tasks.h> include file:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Task {		struct Task {
	struct Node tc_Node;		struct Node tc_Node;
Line 63:		Line 63:
	Once the structure has been initialized, it must be linked to Exec. This is done with a call to AddTask() in which the following parameters are specified:		Once the structure has been initialized, it must be linked to Exec. This is done with a call to AddTask() in which the following parameters are specified:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	AddTask(struct Task *task, APTR initialPC, APTR finalPC )		AddTask(struct Task *task, APTR initialPC, APTR finalPC )
	</syntaxhighlight>		</syntaxhighlight>
Line 75:		Line 75:
	The recommended of creating a task is with CreateTask() or CreateTaskTags() functions.		The recommended of creating a task is with CreateTask() or CreateTaskTags() functions.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	CreateTaskTags(CONST_STRPTR name, int32 priority, CONST_APTR initialPC, uint32 stacksize, ...);		CreateTaskTags(CONST_STRPTR name, int32 priority, CONST_APTR initialPC, uint32 stacksize, ...);
	</syntaxhighlight>		</syntaxhighlight>
Line 89:		Line 89:
	{{Note\|title=''Keep This In Mind.''\|text=Because the simple task's code is a function in our program, we must stop the subtask before exiting.}}		{{Note\|title=''Keep This In Mind.''\|text=Because the simple task's code is a function in our program, we must stop the subtask before exiting.}}

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// simpletask.c - Uses the function CreateTaskTags() to create a simple subtask.		// simpletask.c - Uses the function CreateTaskTags() to create a simple subtask.

Line 213:		Line 213:
	It is never necessary to both Disable() and Forbid(). Because disabling prevents interrupts, it also prevents preemptive task scheduling. When disable is used within an interrupt, it will have the effect of locking out all higher level interrupts (lower level interrupts are automatically disabled by the CPU). Many Exec lists can only be accessed while disabled. Suppose you want to print the names of all system tasks. You would need to access both the TaskReady and TaskWait lists from within a single disabled section. In addition, you must avoid calling system functions that would break a disable by an indirect call to Wait() (Printf() for example). In this example, the names are gathered into a list while task switching is disabled. Then task switching is enabled and the names are printed.		It is never necessary to both Disable() and Forbid(). Because disabling prevents interrupts, it also prevents preemptive task scheduling. When disable is used within an interrupt, it will have the effect of locking out all higher level interrupts (lower level interrupts are automatically disabled by the CPU). Many Exec lists can only be accessed while disabled. Suppose you want to print the names of all system tasks. You would need to access both the TaskReady and TaskWait lists from within a single disabled section. In addition, you must avoid calling system functions that would break a disable by an indirect call to Wait() (Printf() for example). In this example, the names are gathered into a list while task switching is disabled. Then task switching is enabled and the names are printed.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// tasklist.c - Snapshots and prints the ExecBase task list		// tasklist.c - Snapshots and prints the ExecBase task list
	#include <exec/types.h>		#include <exec/types.h>
Line 491:		Line 491:
	To allocate any trap, you can use the following code:		To allocate any trap, you can use the following code:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	if (-1 == (trap = IExec->AllocTrap(-1)))		if (-1 == (trap = IExec->AllocTrap(-1)))
	IDOS->Printf("all trap instructions are in use\n");		IDOS->Printf("all trap instructions are in use\n");
Line 498:		Line 498:
	Or you can select a specific trap using this code:		Or you can select a specific trap using this code:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	if (-1 == (trap = IExec->AllocTrap(3)))		if (-1 == (trap = IExec->AllocTrap(3)))
	IDOS->Printf("trap #3 is in use\n");		IDOS->Printf("trap #3 is in use\n");

Janne Peräaho: Added code review request

2018-09-20T13:52:11Z

Added code review request

← Older revision		Revision as of 13:52, 20 September 2018
Line 1:		Line 1:
	{{NeedUpdate}}		{{NeedUpdate}}{{CodeReview}}
	== Exec Tasks ==		== Exec Tasks ==

Steven Solie: /* Task Creation With CreateTask() */

2016-10-11T17:07:38Z

Task Creation With CreateTask()

← Older revision		Revision as of 17:07, 11 October 2016
Line 114:		Line 114:
	sharedvar = 0;		sharedvar = 0;

	struct Task *task = CreateTaskTags("SimpleTask", 0 , (CONST_APTR)simpletask, STACK_SIZE,		struct Task *task = IExec->CreateTaskTags("SimpleTask", 0, (CONST_APTR)simpletask, STACK_SIZE,
	TAG_END);		TAG_END);

Steven Solie: /* Task Creation With CreateTask() */

2016-10-08T14:52:03Z

Task Creation With CreateTask()

← Older revision		Revision as of 14:52, 8 October 2016
Line 76:		Line 76:

	<syntaxhighlight>		<syntaxhighlight>
	CreateTaskTags(CONST_STRPTR name, int32 priority, ~~APTR~~ initialPC, uint32 stacksize, ...);		CreateTaskTags(CONST_STRPTR name, int32 priority, CONST_APTR initialPC, uint32 stacksize, ...);
	</syntaxhighlight>		</syntaxhighlight>

Line 114:		Line 114:
	sharedvar = 0;		sharedvar = 0;

	struct Task *task = CreateTaskTags("SimpleTask", 0 , simpletask, STACK_SIZE,		struct Task *task = CreateTaskTags("SimpleTask", 0 , (CONST_APTR)simpletask, STACK_SIZE,
	TAG_END);		TAG_END);

Line 130:		Line 130:
	/* any system calls which could cause it to be awakened or signalled later. */		/* any system calls which could cause it to be awakened or signalled later. */
	IExec->Forbid();		IExec->Forbid();
	~~IEXec~~->DeleteTask(task);		IExec->DeleteTask(task);
	IExec->Permit();		IExec->Permit();
	cleanexit("", RETURN_OK);		cleanexit("", RETURN_OK);

Steven Solie: /* Task Creation */

2015-11-03T23:05:51Z

Task Creation

← Older revision		Revision as of 23:05, 3 November 2015
Line 48:		Line 48:

	; tc_Node		; tc_Node
	: The task list node structure. This includes the task's priority, its type, and its name (refer to [[Exec_Lists_and_Queues\|Exec Lists and Queues]] ~~chapter~~).		: The task list node structure. This includes the task's priority, its type, and its name (refer to [[Exec_Lists_and_Queues\|Exec Lists and Queues]]).

	; tc_SPLower		; tc_SPLower

Steven Solie: /* Task Traps */

2013-05-08T19:20:24Z

Task Traps

← Older revision		Revision as of 19:20, 8 May 2013
Line 362:		Line 362:

	The system's default trap handling code generally displays a Software Error Requester or Alert containing an exception number and the program counter or task address. Processor exceptions generally have numbers in the range hex 00 to 2F. The ''68000'' processor exceptions of particular interest are as follows.		The system's default trap handling code generally displays a Software Error Requester or Alert containing an exception number and the program counter or task address. Processor exceptions generally have numbers in the range hex 00 to 2F. The ''68000'' processor exceptions of particular interest are as follows.

⚫	Traps (68000 Exception Vector Numbers)

	{\| class="wikitable"		{\| class="wikitable"
		⚫	\|+ Traps (68000 Exception Vector Numbers)
	\| 2 \|\| Bus error \|\| access of nonexistent memory		\| 2 \|\| Bus error \|\| access of nonexistent memory
	\|-		\|-

Alexandre Balaban: /* Task Exceptions */ Make use of Note template

2012-07-12T13:15:57Z

Task Exceptions: Make use of Note template

← Older revision		Revision as of 13:15, 12 July 2012
Line 353:		Line 353:
	While processing a given exception, Exec prevents that exception from occurring recursively. At exit from your exception-processing code, you should make sure D0 contains the signal mask the exception routine received in D0 because Exec looks here to see which signals it should reactivate. When the task executes the RTS instruction at the end of the exception routine, the system restores the previous contents of all of the task registers and resumes the task at the point where it was interrupted by the exception signal.		While processing a given exception, Exec prevents that exception from occurring recursively. At exit from your exception-processing code, you should make sure D0 contains the signal mask the exception routine received in D0 because Exec looks here to see which signals it should reactivate. When the task executes the RTS instruction at the end of the exception routine, the system restores the previous contents of all of the task registers and resumes the task at the point where it was interrupted by the exception signal.

		⚫	{{Note\|title=''Exceptions Are Tricky''.\|text=Exceptions are difficult to use safely. An exception can interrupt a task that is executing a critical section of code within a system function, or one that has locked a system resource such as the disk or blitter (note that even simple text output uses the blitter.) This possibility makes it dangerous to use most system functions within an exception unless you are sure that your interrupted task was performing only local, non-critical operations.}}
	{\| class="wikitable"
⚫	\| ''Exceptions Are Tricky''. Exceptions are difficult to use safely. An exception can interrupt a task that is executing a critical section of code within a system function, or one that has locked a system resource such as the disk or blitter (note that even simple text output uses the blitter.) This possibility makes it dangerous to use most system functions within an exception unless you are sure that your interrupted task was performing only local, non-critical operations.
	\|}

	== Task Traps ==		== Task Traps ==

Alexandre Balaban: /* Task Exclusion */ Make use of Note template

2012-07-12T13:14:13Z

Task Exclusion: Make use of Note template

← Older revision		Revision as of 13:14, 12 July 2012
Line 186:		Line 186:
	== Task Exclusion ==		== Task Exclusion ==

	From time to time the advanced system program may find it necessary to access global system data structures. Because these structures are shared by the system and by other tasks that execute asynchronously to your task, a task must prevent other tasks from using these structures while it is reading from or writing to them. Task exclusion methods described below prevent the operating system from switching tasks by ''forbidding'' or ''disabling''. A section of code that requires the use of either of these mechanisms to lock out access by others is termed a ''critical section''. '''Use of these methods is discouraged. For arbitrating access to data between your tasks, ''mutexes'' are a superior solution (See [[Exec_Mutexes\|Exec Mutexes]]). The below solution is deprecated and will be removed from the AmigaOS soon.		From time to time the advanced system program may find it necessary to access global system data structures. Because these structures are shared by the system and by other tasks that execute asynchronously to your task, a task must prevent other tasks from using these structures while it is reading from or writing to them. Task exclusion methods described below prevent the operating system from switching tasks by ''forbidding'' or ''disabling''. A section of code that requires the use of either of these mechanisms to lock out access by others is termed a ''critical section''.
			{{Note\|title=Use of these methods is discouraged!\|text='''For arbitrating access to data between your tasks, ''mutexes'' are a superior solution (See [[Exec_Mutexes\|Exec Mutexes]]). The below solution is deprecated and will be removed from the AmigaOS soon.'''}}

	=== Forbidding Task Switching ===		=== Forbidding Task Switching ===
Line 208:		Line 209:
	Like forbidden sections, disabled sections can be nested. To restore normal interrupt processing, an Enable() call must be made for every Disable(). Also like forbidden sections, any direct or indirect call to the Wait() function will enable interrupts until the task regains the processor.		Like forbidden sections, disabled sections can be nested. To restore normal interrupt processing, an Enable() call must be made for every Disable(). Also like forbidden sections, any direct or indirect call to the Wait() function will enable interrupts until the task regains the processor.

		⚫	{{Note\|title=''WARNING: It is important to realize that there is a danger in using disabled sections''.\|text=Because the software on the Amiga depends heavily on its interrupts occurring in nearly real time, you cannot disable for more than a very brief instant. Disabling interrupts for more than 250 microseconds can interfere with the normal operation of vital system functions, especially serial I/O.}}
	{\| class="wikitable"
⚫	\| ''WARNING: It is important to realize that there is a danger in using disabled sections''. Because the software on the Amiga depends heavily on its interrupts occurring in nearly real time, you cannot disable for more than a very brief instant. Disabling interrupts for more than 250 microseconds can interfere with the normal operation of vital system functions, especially serial I/O.
	\|}

	It is never necessary to both Disable() and Forbid(). Because disabling prevents interrupts, it also prevents preemptive task scheduling. When disable is used within an interrupt, it will have the effect of locking out all higher level interrupts (lower level interrupts are automatically disabled by the CPU). Many Exec lists can only be accessed while disabled. Suppose you want to print the names of all system tasks. You would need to access both the TaskReady and TaskWait lists from within a single disabled section. In addition, you must avoid calling system functions that would break a disable by an indirect call to Wait() (Printf() for example). In this example, the names are gathered into a list while task switching is disabled. Then task switching is enabled and the names are printed.		It is never necessary to both Disable() and Forbid(). Because disabling prevents interrupts, it also prevents preemptive task scheduling. When disable is used within an interrupt, it will have the effect of locking out all higher level interrupts (lower level interrupts are automatically disabled by the CPU). Many Exec lists can only be accessed while disabled. Suppose you want to print the names of all system tasks. You would need to access both the TaskReady and TaskWait lists from within a single disabled section. In addition, you must avoid calling system functions that would break a disable by an indirect call to Wait() (Printf() for example). In this example, the names are gathered into a list while task switching is disabled. Then task switching is enabled and the names are printed.

Alexandre Balaban: /* Task Termination */ Make use of the Note template

2012-07-12T13:07:38Z

Task Termination: Make use of the Note template

← Older revision		Revision as of 13:07, 12 July 2012
Line 182:		Line 182:
	It is wise to adopt a strategy for task clean-up responsibility. You should decide whether resource allocation and deallocation is the duty of the creator task or the newly created task. Often it is easier and safer for the creator to handle the resource allocation and deallocation on behalf of its offspring. In such cases, before removing the child task, you must make sure it is in a safe state such as Wait(0L) and not still using a resources or waiting for an event or signal that might still occur.		It is wise to adopt a strategy for task clean-up responsibility. You should decide whether resource allocation and deallocation is the duty of the creator task or the newly created task. Often it is easier and safer for the creator to handle the resource allocation and deallocation on behalf of its offspring. In such cases, before removing the child task, you must make sure it is in a safe state such as Wait(0L) and not still using a resources or waiting for an event or signal that might still occur.

		⚫	{{Note\|Certain resources, such as signals and created ports, must be allocated and deallocated by the same task that will wait on them. Also note that if your subtask code is part of your loaded program, you must not allow your program to exit before its subtasks have cleaned up their allocations, and have been either deleted or placed in a safe state such as Wait(0).}}
	{\| class="wikitabl"
⚫	\| ~~''NOTE:''~~ Certain resources, such as signals and created ports, must be allocated and deallocated by the same task that will wait on them. Also note that if your subtask code is part of your loaded program, you must not allow your program to exit before its subtasks have cleaned up their allocations, and have been either deleted or placed in a safe state such as Wait(0).
	\|}

	== Task Exclusion ==		== Task Exclusion ==

Alexandre Balaban: /* Task Stack */ Make use of Note template

2012-07-12T13:05:59Z

Task Stack: Make use of Note template

← Older revision		Revision as of 13:05, 12 July 2012
Line 159:		Line 159:
	'''Because stack-bounds checking is not provided as a service of Exec, it is important to provide enough space for your task stack. Stack overflows are always difficult to debug and may result not only in the erratic failure of your task but also in the mysterious malfunction of other Amiga subsystems.''' Some compilers may provide a stack-checking option.		'''Because stack-bounds checking is not provided as a service of Exec, it is important to provide enough space for your task stack. Stack overflows are always difficult to debug and may result not only in the erratic failure of your task but also in the mysterious malfunction of other Amiga subsystems.''' Some compilers may provide a stack-checking option.

		⚫	{{Note\|title=''You Can't Always Check The Stack.''\|text=Such stack-checking options generally cannot be used if part of your code will be running on the system stack (interrupts, exceptions, handlers, servers) or on a different task's stack (libraries, devices, created tasks).}}
	{\| class="wikitable"
⚫	\| ''You Can't Always Check The Stack.'' Such stack-checking options generally cannot be used if part of your code will be running on the system stack (interrupts, exceptions, handlers, servers) or on a different task's stack (libraries, devices, created tasks).
	\|}

	When choosing your stack size, do not cut it too close. Remember that any recursive routines in your code may use varying amounts of stack, and that future versions of system routines may use additional stack variables. By dynamically allocating buffers and arrays, most application programs can be designed to function comfortably within the recommended minimum process stack size of 16000 bytes.		When choosing your stack size, do not cut it too close. Remember that any recursive routines in your code may use varying amounts of stack, and that future versions of system routines may use additional stack variables. By dynamically allocating buffers and arrays, most application programs can be designed to function comfortably within the recommended minimum process stack size of 16000 bytes.