NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <exec/chExec.h>int svActorStopHandlerConnect(KnCap * actorcap, unsigned int vectindex, KnLapDesc * newhandler);
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 svActorStopHandler() calls are used to manage stop handlers associated with the actor whose capability is pointed to by actorcap . These calls are restricted to SUPERVISOR threads.
svActorStopHandlerConnect() duplicates the LAP descriptor pointed to by newhandler into the specified entry of the stop handler's vector.
svActorStopHandlerDisconnect clears the LAP descriptor stored in the specified entry of the stop handler's vector. If curhandler is not equal to K_CONNECTED_LAP , it must point to a LAP descriptor identical to the LAP descriptor currently installed.
svActorStopHandlerGetConnected() copies, at the location pointed to by curhandler , the LAP descriptor currently installed in the stop handler's vector.
The stop handlers are invoked as a consequence of a threadStop(2K_I) or an actorStop(2K_I) system call. When invoked as a result of an actorStop() call, they are called for all the threads that appear in the actor being stopped. If a thread has performed a safe LAP in an actor, it has at least one LAP frame in this actor. In this case, the stop handlers are called for every LAP frame that appears in the actor.
Stop handlers are specified in the form of LAP descriptors (see svLapCreate(2K) ).
As several subsystem managers may need to control the stopped state of a thread, the microkernel keeps a vector of K_ACTOR_STOPVECT_MAX stop handlers per actor.
The vectindex parameter identifies which entry of the stop handler's vector should be used by the calls. The consistent allocation of vector indexes among subsystem managers is the responsibility of the subsystem managers. Depending on the subsystems, the last vector entry may be reserved for use by the application. For this purpose, the constant K_ACTOR_STOPVECT_LAST can be used independently of the system configuration to designate the index K_ACTOR_STOPVECT_MAX - 1 .
The stop handlers are usually called by the stopped thread just before it actually stops (K_STOP_INCTX ). However, if the thread being stopped is blocked in a blocking system call, or if it has left the current stopped actor through a lapInvoke(2K) system call, stop handlers are called by the thread which performs the stop action ( K_STOP_OUTCTX ).
In any case stop handlers are invoked in sequence, starting from index 0, until one of them succeeds in processing the stop event (sets the K_STOP_COMPLETED status, for example).
The argument of the LAP stop handler is a pointer to a KnActorStopDesc data structure. This structure has the following fields:
KnStopMode stopMode ; KnStopStatus* stopStatus ; int topFrameLevel ; int curFrameLevel ; KnStopThStatus* threadStatus ; KnThreadLid threadLid ; KnThreadCtx* threadCtx ;
The stopMode field indicates whether or not the stop handlers are called in the context of the stopping thread (K_STOP_INCTX vs K_STOP_OUTCTX ).
The stopStatus field may be used by the stop handler to indicate that the stop has been successfully processed. The stop handler is called with stopStatus pointing to a status variable set to K_STOP_INPROGRESS . The handler can indicate that it has completed the stop processing by setting this status variable to K_STOP_COMPLETED . In this case no other stop handlers are invoked.
The topFrameLevel and curFrameLevel fields are used to represent the top and current LAP frames respectively. The top LAP frame is the one identified by the highest LAP frame level (see svLapCreate(2K) ).
The threadStatus field is used to specify whether or not the thread must be stopped when returning from the stop handler invocation. The corresponding values are K_STOP_THREADSTART and K_STOP_THREADSTOP .
The threadLid field describes the thread for which the stopping action must be performed.
The threadCtx field provides access to the register context of the stopped thread. This context is processor-dependent. The given context does not depend on the invocation mode ( K_STOP_INCTX vs K_STOP_OUTCTX ). This is always the valid thread's context in the stopped actor.
On success, the calls return K_OK . Otherwise, a negative error code is returned.
svActorStopHandlerConnect is called and there is already a valid LAP descriptor installed in the specified entry of the stop handler's vector.
actorcap is an inconsistent actor capability or vectindex is invalid. The curhandler LAP descriptor passed to svActorStopHandlerDisconnect() is not equal to K_CONNECTED_LAP and does not match the LAP descriptor currently installed.
actorcap does not specify a local actor.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
actorStop(2K_I) , lapInvoke(2K) , svLapCreate(2K) , threadStop(2K)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO