NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO
#include <mon/chMon.h>int svThreadProbeConnect(KnCap * actorcap, KnThreadLid threadli, MonThreadProbe * probe);
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.
MON
The svThreadProbeConnect() microkernel call connects a monitoring probe to a thread. The svThreadProbeDisconnect() microkernel call disconnects a monitoring probe from a thread.
The threadli parameter is the local identifier of the target thread. The actorcap parameter is a pointer to the capability of the target thread's actor. The probe parameter describes the monitoring probe. It is a pointer to a MonThreadProbe structure whose member is the following:
MonThreadVtbl* vtbl ;
The vtbl member specifies the notification routines associated with the probe. It is a pointer to a MonThreadVtbl structure whose members are the following:
/* House keeping */ int vtbl_sizeof; Thread_connection connection; Thread_disconnection disconnection; Thread_deletion deletion; /* Monitoring inheritance */ Thread_actorCreation actorCreation; Thread_threadCreation threadCreation; Thread_portCreation portCreation; /* User specific events */ Thread_monUser monUser; /* traps and exceptions */ Thread_trapEnter trapEnter; Thread_trapLeave trapLeave; /* Scheduling */ Thread_signal signal; Thread_wait wait; Thread_switchOn switchOn; Thread_switchOff switchOff;
The vtbl_sizeof member must be set to sizeof(MonThreadVtbl) . It is provided for compatibility between different releases of the microkernel.
The other members of the MonThreadVtbl structure are pointers to functions. Each member must either be NULL , or point to the implementation of a specific notification routine associated with the probe. If non NULL , the notification routine will be invoked on each occurrence of the associated event. If NULL , no invocation is made.
The data for the MonThreadProbe structure, for the MonThreadVtbl structure, and the code for the monitoring routines must belong to supervisor space and must be locked in physical memory. The notification routines are executed in supervisor execution mode. Except where stated explicitly, they must not to re-enter the microkernel except via a few permitted system calls.
void connection (probe, threadstate) MonThreadProbe* probe; MonThreadState* threadstate;
The connection() routine is invoked after the probe has been connected to a thread. The probe parameter is a pointer to the connected probe (passed as an argument to the svThreadProbeConnect() microkernel call). The state parameter is a pointer to a MonThreadState structure, which represents the actor internally within the microkernel address space (see svThreadMonConst(2MON) ). This pointer is valid for the lifetime of the thread.
void disconnection (probe) MonThreadProbe* probe;
The disconnection() routine is invoked after a probe has been disconnected from a thread. The probe parameter is a pointer to the probe concerned.
void deletion (probe) MonThreadProbe* probe;
The deletion() routine is invoked after the actor has been deleted. The probe parameter is a pointer to the probe of the thread.
MonActorProbe* actorCreation (probe, actorstate) MonThreadProbe* probe; MonActorState* actorstate;
The actorCreation() routine is invoked after an actor has been created by a monitored thread (see actorCreate(2K) ). The probe parameter is a pointer to the probe of the creating thread. The actorstate parameter is a pointer to a MonActorState structure, which represents the created actor internally within the microkernel address space (see svActorMonConst(2MON) ). This pointer is valid for the lifetime of the actor and is guaranteed to remain valid while the notification routine is executed. The notification routine must return either NULL or a pointer to a monitoring probe for the created thread. In the latter case, the created actor will be monitored.
MonThreadProbe* threadCreation (probe, actorstate, threadstate, stopped) MonThreadProbe* probe; MonActorState* actorstate; MonThreadState* threadstate; int* stopped;
The threadCreation() routine is invoked after a thread has been created by a monitored thread (see threadCreate(2K) ). The probe parameter is a pointer to the probe of the creating thread. The threadstate parameter is a pointer to a MonThreadState structure, which represents the created thread internally within the microkernel address space (see svThreadMonConst(2MON) ). This pointer is valid for the lifetime of the thread and is guaranteed to remain valid while the notification routine is executed. The notification routine must return either NULL or a pointer to a monitoring probe for the created thread. In the latter case, the created thread will be monitored. The stopped parameter is a pointer to an integer whose value is preset to NULL . If the created thread should stay in the stopped state (for example in debugging situations), the integer must be set to a non- NULL value. In this case, the thread will return to its original created state when threadStart(2K) is called.
MonPortProbe* portCreation (probe, portstate, threadstate) MonThreadProbe* probe; MonPortState* portstate; MonThreadState* threadstate;
The portCreation() routine is invoked after a port has been created by a monitored thread (see portCreate(2K) ). The probe parameter is a pointer to the probe of thecreating thread. The portstate parameter is a pointer to a MonPortState structure, which represents the created port internally within the microkernel address space (see svPortMonConst(2MON) ). This pointer is valid for the lifetime of the port and is guaranteed to remain valid while the notification routine is executed. The notification routine must return either NULL or a pointer to a monitoring probe for the created thread. In the latter case, the created port will be monitored.
void monUser (probe, evtno, addr, size) MonThreadProbe* probe; int evtno; VmAddr addr; VmSize size;
The monUser() notification routine is invoked as a consequence of the threadMonUser(2MON) microkernel call. The probe parameter is a pointer to the probe of the thread which performed the threadMonUser() call. The evtno , addr and size parameters are the same as those given as parameters to the threadMonUser() call.
void trapEnter (probe, threadctx) MonThreadProbe* probe; KnThreadCtx* threadctx;
The
trapEnter()
notification routine is invoked after a thread has performed a trap or an exception (see
svTrapConnect(2K)
), but before the trap (exception) is handled by the system. The
probe
parameter is a pointer to the probe of the thread which performed the trap. The
threadctx
parameter is a pointer to the trap context, which is a structure of the
KnThreadCtx
type. The
trapNb
member in the
KnThreadCtx
structure is the (absolute) trap number.
void trapLeave (probe, threadctx) MonThreadProbe* probe; KnThreadCtx* threadctx;
The
trapLeave()
notification routine is invoked after a thread has performed a trap or an exception (see
svTrapConnect(2K)
), and after the trap (exception) has been handled by the system. The
probe
parameter is a pointer to the probe of the thread which performed the trap. The
threadctx
parameter is a pointer to the trap context, which is a structure of the
KnThreadCtx
type. The
trapNb
member in the
KnThreadCtx
structure is the (absolute) trap number.
void signal (probe) MonThreadProbe* probe;
The signal() notification routine is invoked after a thread has been signalled by the microkernel executive to enter the scheduler run queue. The probe parameter is a pointer to the probe of the thread which was signalled.
void wait (probe) MonThreadProbe* probe;
The wait() notification routine is invoked after a thread has opted to wait and leave the scheduler run queue. The probe parameter is a pointer to the probe of the thread which has opted to wait.
void switchOn (probe) MonThreadProbe* probe;
The switchOn() notification routine is invoked before a thread starts running on a processor. The probe parameter is a pointer to the probe of the thread concerned.
void switchOff (probe) MonThreadProbe* probe;
The switchOff() notification routine is invoked after a thread has stopped running on a processor. The probe parameter is a pointer to the probe of the involved thread.
The semantics of the signal() , wait() , switchOn() , and switchOff() routines are illustrated by the diagram below.
+-------------+ +-------------+ / signal() \\\\ / switchOn() \\\\ / V / V +-----------+ +----------+ +----------+ | Thread | | Thread | | Thread | | not ready | | ready | | running | +-----------+ +----------+ +----------+ ^ ^ / / \\\\ \\\\ switchOff() / / \\\\ +-------------+ / +----------------------------------------+ wait(), switchOff()
Upon successful completion, both microkernel calls return 0 . Otherwise, a negative error code is returned.
An attempt was made to connect a probe while another probe was already connected to the thread.
An attempt was made to disconnect a probe which was not connected to the thread.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
svSiteProbeConnect(2MON) , svActorProbeConnect(2MON) , svPortProbeConnect(2MON) , svThreadMonConst(2MON)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO