NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <exec/chExec.h>int actorCreate(KnCap *actorinit, KnCap *actorcap, KnActorPrivilege privilege, KnActorStatus status);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
CORE
The actorCreate() call creates a new actor. The 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 */
uiis the unique identifier of the actor, and
keyis 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 the actor that initializes it, the actor whose capability is given by actorinit. If actorinit is K_MYACTOR, the current actor is taken as the initializing actor. The CORE feature attributes inherited from the init actor include the exception handler (see svExcHandler(2K)) and the abort handler (see svAbortHandler(2K)). Other features such as those involving communication may also define attributes inherited by the new actor.
The privilege field gives the actor privilege. Two main privileges may be given to an actor, USER or SYSTEM. System actor threads have access to certain privileged microkernel calls even if they do not have SUPERVISOR privileges (see threadCreate(2K)). A SYSTEM actor may only be created by a thread running with SUPERVISOR privileges, or if its actor is a SYSTEM actor.
In addition, SYSTEM actors may be created as SUPERVISOR actors. A SUPERVISOR actor shares the microkernel 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. In debug mode, more information than usual about thread execution will be gathered by the system to support certain 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 initializing 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 | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO