procmgr_value_notify

Add an event to be triggered when a monitored value crosses a trigger point

Synopsis:

#include <sys/procmgr.h>

int procmgr_value_notify_add( unsigned type,
                              int sub_id,
                              uint64_t value,
                              const struct sigevent *event );

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Arguments:

type

The type of event you want to add; one of the following:

PROCMGR_VALUE_FREE_MEM—the amount of system free memory
PROCMGR_VALUE_PRIVATE_MEM—the amount of MAP_PRIVATE memory for a process

You can OR this with one of the following:

PROCMGR_VALUE_TRIGGER_UP—deliver the event when the value rises to the trigger point
PROCMGR_VALUE_TRIGGER_DOWN—deliver the event when the value drops to the trigger point

sub_id

A sub-ID associated with the type:

For PROCMGR_VALUE_FREE_MEM, specify 0 for the total memory.
For PROCMGR_VALUE_PRIVATE_MEM, specify the process ID of the process.

value

The trigger point.

event

A pointer to the sigevent that you want to be delivered. The application must register the event by calling MsgRegisterEvent() with SYSMGR_COID passed as the connection ID (coid) before calling procmgr_value_notify_add().

Description:

The procmgr_value_notify_add() function sets up an event to be triggered when the value being monitored crosses the trigger point up (PROCMGR_VALUE_TRIGGER_UP) or down (PROCMGR_VALUE_TRIGGER_DOWN).

For example, PROCMGR_VALUE_FREE_MEM | PROCMGR_VALUE_TRIGGER_DOWN causes the event to be delivered when the system free memory drops to the specified trigger value.

If you just want to read the value with procmgr_value_current(), don't specify either of the trigger bits.

To delete the notification, call procmgr_event_notify_delete(), passing it the ID that procmgr_value_notify_add() returns.

Returns:

An event ID, or -1 if there was an error (errno is set).

Examples:

This example demonstrates how to use procmgr_value_notify_add() with MsgRegisterEvent() to set up a notification to be delivered when the system's free memory drops below the specified trigger value:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/neutrino.h>
#include <sys/procmgr.h>
#include <signal.h>

#define VALUE_CHANGED_CODE   (_PULSE_CODE_MINAVAIL + 2)

int main(int argc, char **argv) {

   int chid, coid, rc, handle;
   struct sigevent event;
   struct _pulse msg;
   uint64_t trigger_value = 100;

   chid = ChannelCreate(_NTO_CHF_PRIVATE);
   if (chid == -1) {
       perror("ChannelCreate() failed");
       exit(EXIT_FAILURE);
   }

   coid = ConnectAttach(0, 0, chid, _NTO_SIDE_CHANNEL, _NTO_COF_CLOEXEC);
   if (coid == -1) {
       perror("ConnectAttach() failed");
       exit(EXIT_FAILURE);
   }

   SIGEV_PULSE_INIT(&event, coid, SIGEV_PULSE_PRIO_INHERIT, VALUE_CHANGED_CODE, 0);
   SIGEV_MAKE_UPDATEABLE(&event);

   if (MsgRegisterEvent(&event, chid) == -1) {
      perror("MsgRegisterEvent() failed");
      exit(EXIT_FAILURE);
   }

   /*
    * Ask to be notified via a pulse whenever a specific value changes
    */
   handle = procmgr_value_notify_add(PROCMGR_VALUE_FREE_MEM | PROCMGR_VALUE_TRIGGER_DOWN,
                                     0, trigger_value, &event);
   if (handle == -1) {
       perror("procmgr_value_notify_add() failed");
       exit(EXIT_FAILURE);
   }

   for (;;) {
       rc = MsgReceivePulse(chid, &msg, sizeof(msg), NULL);
       if (rc == -1) {
           perror("MsgReceivePulse() failed");
           exit(EXIT_FAILURE);
       }

       switch(msg.code) {
           case VALUE_CHANGED_CODE:
               printf("The specified value has changed\n");
               break;
       }
   }
   procmgr_event_notify_delete(handle);
   return 0;
}

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes