ChorusOS man pages section 2MON: Monitoring Services

svThreadProbeConnect(2MON)

NAME

svThreadProbeConnect, svThreadProbeDisconnect- Connect a monitoring probe to a thread; Disconnect a monitoring probe from a thread

SYNOPSIS

#include <mon/chMon.h>

actorcap

threadli

probe

actorcap

threadli

probe

FEATURES

MON

DESCRIPTION

The svThreadProbeConnect kernel call connects a monitoring probe to a thread. The svThreadProbeDisconnect kernel 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 kernel.

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 (this is described later on in this manual page). If null, no invocation is done.

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 explicitly stated, they must not to re-enter the kernel except via a few permitted system calls (see svIntrConnect(2K)).

DESCRIPTION OF THE NOTIFICATION ROUTINES

The notification routines are the following:

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 kernel call). The state parameter is a pointer to a MonThreadState structure, which represents the actor internally within the kernel address space (see svMonThreadConst (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 thread's probe.

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 creating thread's probe. The actorstate parameter is a pointer to a MonActorState structure, which represents the created actor internally within the kernel address space (see svMonActorConst (2MON)). This pointer is valid for the lifetime of the actor and is guaranteed to remain valid while the notification routine is being 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 creating thread's probe. The threadstate parameter is a pointer to a MonThreadState structure, which represents the created thread internally within the kernel address space (see svMonThreadConst (2MON)). This pointer is valid for the lifetime of the thread and is guaranteed to remain valid while the notification routine is being 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 creating thread's probe. The portstate parameter is a pointer to a MonPortState structure, which represents the created port internally within the kernel address space (see svMonPortConst (2MON)). This pointer is valid for the lifetime of the port and is guaranteed to remain valid while the notification routine is being 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) kernel 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 micro-kernel 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()

RETURN VALUE

Upon successful completion, both kernel calls return 0. Otherwise, a negative error code is returned.

ERRORS

[K_EBUSY]: An attempt was made to connect a probe while another probe was already connected to the thread.
[K_EINVAL]: An attempt was made to disconnect a probe which was not connected to the thread.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving