NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <exec/chExec.h>int actorCreate(KnCap *actorinit, KnCap *actorcap, KnActorPrivilege privilege, KnActorStatus status);
CORE
The actorCreate call creates a new actor. A capability for this actor is returned in actorcap, which is a pointer to a KnCap structure whose members are the following:
KnUniqueId ui ; /* entity name */ KnKey key ; /* modification key */ |
Where ui is the unique identifier of the actor, and key is the key needed to modify the actor (for instance, creating or deleting threads or other resources, or stopping the actor).
The new actor inherits a number of attributes from its init actor, whose capability is given by actorinit . If actorinit is K_MYACTOR, the current actor is taken as the init actor. The CORE module attributes inherited from the init actor are: the exception handler (see svExcHandler(2K)) and the abort handler (see svAbortHandler(2K)). Furthermore, other kernel modules, such as communication modules, may define attributes which are inherited by the new actor.
The privilege field gives the actor's privilege. Two main privileges may be given to an actor: USER or SYSTEM. A system actor's thread has access to some privileged kernel calls even if the thread is not running with the SUPERVISOR privilege level (see threadCreate(2K)). A SYSTEM actor may only be created by a thread running with the SUPERVISOR privilege or if its actor is a SYSTEM actor.
In addition, SYSTEM actors may be created as SUPERVISOR actors: a SUPERVISOR actor shares the kernel address space, and no user address space is allocated to it. SUPERVISOR actors may only contain SUPERVISOR threads.
A USER actor is created with privilege equal to K_USERACTOR; a SYSTEM actor is created with privilege equal to K_SYSTEMACTOR; a SUPERVISOR actor is created with privilege equal to K_SUPACTOR.
When created, the new actor contains neither thread nor memory region.
The status parameter is the initial actor status: if the K_STOPPED flag is set in the status parameter, the new actor is created in the STOPPED state. That means that even if threads are created in the actor (using threadCreate(2K)), none of these threads are able to run until the actor is put into the ACTIVE state using actorStart(2K).
If the K_STOPPED flag is not set, threads that are created in the ACTIVE state are able to run immediately.
if the K_DEBUGMODE flag is set in the status parameter, the new actor will be put into the DEBUGMODE mode. That means that more information than usual about thread execution will be gathered by the system. This helps to support some source level debuggers.
The maximum number of actors that may be created on a site is tunable parameter.
Upon successful completion a value of 0 is returned. Otherwise, a negative error code is returned.
actorinit is an inconsistent actor capability.
actorinit does not specify a reachable actor.
Some of the data provided are outside the current actor's address space.
The system is out of resources.
The current thread is not allowed to create a SYSTEM actor.
The init actor and the current actor must be located on the same site.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO