Dynamic Probe Class Library

Dynamic Probe Class Library Programming Guide


Chapter 14. Handling signals and file descriptors through the DPCL system

The DPCL system manages a variety of signals and file descriptors in order to enable analysis tools to effectively instrument one or more target application processes. Socket connections from the analysis tool to the various DPCL communication daemons, for example, are represented by file descriptors that the DPCL system monitors using the UNIX system call select in order to detect when a message has arrived from a DPCL communication daemon. Similarly, certain signals are handled by the DPCL system in order to implement features such as phase probes and one-shot probes. As a programming convenience for you, the developer of DPCL analysis tools, the DPCL system enables you to add additional signals and file descriptors to the lists of those it monitors. When these additional signals occur, or when these additional file descriptors are ready to be read, the DPCL system will call a function handler that you have specified. The function for adding signals to the list of those managed by the DPCL system is the Ais_add_signal function and is described in more detail in Handling signals through the DPCL system. The function for adding file descriptors to the list of those managed by the DPCL system is the Ais_add_fd function and is described in more detail in Handling file descriptors through the DPCL system.


Handling signals through the DPCL system

In DPCL analysis tools, signal handlers that you set up using the UNIX sigaction function will not be able to call DPCL functions. This restriction is in addition to the standard restrictions regarding functions that cannot be called within a sigaction signal handler as outlined in the sigaction man page. Using the DPCL Ais_add_signal function, however, you can specify a signal handler that will be called by the DPCL system rather than by the sigaction function. Signal handlers set up using the Ais_add_signal function have none of the sigaction function's restrictions on what functions they may call. The prototype for the Ais_add_signal function is contained in the DPCL header file AisHandler.h.

Signal handlers set up using Ais_add_signal and so executed by the DPCL system will be called at safe points so as not to interfere with the DPCL system calls. The DPCL system will pass the signal handler a single parameter value -- the signal number. If the DPCL system is already processing a request, a signal handler registered by the Ais_add_signal function will be executed only after processing of the current request has completed. You should be aware that, depending on the processing required for any particular request, there may be some delay in processing the signal. If delays in processing are not acceptable in your program, and your signal handler does not call any DPCL function, then you should consider using the sigaction function to establish the signal handler. Setting up signal handlers by issuing both the sigaction and Ais_add_signal functions on the same signal within the same DPCL program is allowed. The last one called will override the first. The only restriction is that, if Ais_add_signal is used and a subsequent sigaction is issued against the same signal, the old action returned by sigaction should not be chained to the signal handler set up by sigaction. This is because, by chaining the handlers together, the function handler specified by Ais_add_signal would be called when the signal is raised, and not at safe points as it would be with the DPCL handler.

The following example code uses two calls to the Ais_add_signal function to specify signal handlers for the SIGINT and SIGALRM signals. In this example, the SIGINT signal will be handled by the sighandler function, and the SIGALRM signal will be handled by the sighandler_ALRM function.

Ais_add_signal(SIGINT,sighandler);

Ais_add_signal(SIGALRM,sighandler_ALRM);

 

.

.

.

 

int sighandler(int sig_num){

  Ais_end_main_loop();

  

  FILE *fileout=fopen(FILEOUT,"w");

  int num_tested=0;

  fprintf(fileout,"Source file \"%s\":\n",filename);

  if (fun_count == 0){

     fprintf(fileout," No function found!!\n");

  } else {

     fprintf(fileout,"\nNumber of times each function was executed:\n");

     for (int i=0; i< num_installed; i++){

         fprintf(fileout," %s\t\t%d\n",fun_arr[i].funname,fun_arr[i].pcount);

         if (fun_arr[i].pcount >0) num_tested++;

     }

     fprintf(fileout," Test coverage = %d %%\n",(num_tested*100)/fun_count);

  }

  fclose(fileout);

  printf("*Please check \"%s\" for the final result.\n",FILEOUT);

 

  return(0);

}

int sighandler_ALRM(int signal){

   print_fun_info();

   alarm(15);

   return(0);

}

Once your analysis tool code has used the Ais_add_signal function to add a signal and signal handler to the list of signals managed by the DPCL system, it can, if it no longer needs to handle the signal, call the Ais_remove_signal function. The Ais_remove_signal function removes the signal and signal handler from the list of signals managed by the DPCL system. An analysis tool can also call the Ais_query_signal function to get a pointer to the signal handler function for a specified signal. For more information on the Ais_add_signal, Ais_remove_signal, and Ais_query_signal functions, refer to their UNIX man pages or their entries in the DPCL Class Reference.


Handling file descriptors through the DPCL system

In order to monitor messages from DPCL communication daemons to the DPCL analysis tool, the DPCL system uses the UNIX select subroutine to monitor file descriptors representing the socket connections from the analysis tool to the various DPCL communication daemons running on the remote hosts. The select subroutine sleeps on these file descriptors until a message arrives from one of the daemons. When the select loop detects that a file descriptor is ready for reading, execution breaks out of the loop and the DPCL system reads and otherwise handles the message.

If your analysis tool needs to monitor file descriptors for its own purposes unrelated to DPCL, it can either do this in another program thread, or it can instruct the DPCL system to monitor these additional file descriptors. If the analysis tool does monitor these additional file descriptors in a separate program thread, be aware that this other thread cannot call the DPCL functions or reference DPCL data structures. DPCL is not thread safe; all DPCL function calls must be made from within the same program thread.

In order to easily accommodate analysis tools that also use file descriptors to represent files, sockets, and other I/O devices such as a Motif display variable, the DPCL system enables an analysis tool to add a file descriptor and input handler to the list of those it manages. To instruct the DPCL system to monitor an additional file descriptor, the analysis tool code calls the Ais_add_fd function, supplying it with the file descriptor to be managed and the function handler that the DPCL system should call when the file descriptor is ready for reading. The DPCL system will pass the function handler a single parameter value -- the file descriptor. The prototype for the Ais_add_fd function is contained in the DPCL header file AisHandler.h.

The following example code uses the Ais_add_fd function to instruct the DPCL system to monitor input on the standard input (stdin) file descriptor.

#include <stdio.h>

#include <dpcl.h>

 

int stdin_handler(int);

 

main() {

  Ais_initialize();

 

  printf("example of handler for stdin\n");

  printf("Type any text.  Type 'exit' or 'quit' to end program.\n");

 

  Ais_add_fd(0, stdin_handler);

 

  Ais_main_loop();

 

  Ais_remove_fd(0);

}

 

int stdin_handler(int fd) {

  char s[256];

  gets(s);

  printf("stdin: '%s'\n", s);

 

  if (!strcmp(s, "exit") || !strcmp(s, "quit"))

    Ais_end_main_loop();

  return 0;

}

Once your analysis tool code has used the Ais_add_fd function to add a file descriptor and input handler to the list of file descriptors managed by the DPCL system, it can, if it no longer needs to handle the file descriptor, call the Ais_remove_fd function. The Ais_remove_fd function removes the file descriptor and input handler from the list of file descriptors managed by the DPCL system. For more information on the Ais_add_fd and Ais_remove_fd functions, refer to their UNIX man pages or their entries in the DPCL Class Reference.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]