Difference between revisions of "Demand Predefined Probe"

From OC Systems Wiki!
Jump to: navigation, search
m (Actions On-Demand From Predefined UALs)
 
(2 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
=== The Demand Framework ===
 
=== The Demand Framework ===
  
The demand framework consists of the <code>demand.h</code> include file, the <code>demand.ual</code> probe, and the <code>apdemand</code> command-line script.   
+
The demand framework consists of the <code>demand.h</code> include file, the <code>demand.ual</code> probe, and the [[AUG_Tools_Reference#apdemand|apdemand]] command-line script.   
  
The <code>apdemand</code> command is your way of requesting action.
+
The [[AUG_Tools_Reference#apdemand|apdemand]] command is your way of requesting action.
See [[AUG_Tools_Reference#apdemand|apdemand]] for an overview of <code>apdemand</code>.
 
  
 
The <code>demand</code> UAL needs to be included in Aprobe runs by <code>-u demand</code>,
 
The <code>demand</code> UAL needs to be included in Aprobe runs by <code>-u demand</code>,
Line 33: Line 32:
 
* statprof.ual
 
* statprof.ual
  
Demand snapshots are logged like snapshots you can trigger by naming trigger functions in the config files, but demand needs no internal triggers.  Instead, the trigger is a command you can enter from any shell using <code>apdemand</code>.  
+
Demand snapshots are logged like snapshots you can trigger by naming trigger functions in the config files, but demand needs no internal triggers.  Instead, the trigger is a command you can enter from any shell using [[AUG_Tools_Reference#apdemand|apdemand]].  
 
This may be useful for long-running applications or applications that don't terminate and for which there is no good snapshot location or if you don't know where to place triggers.
 
This may be useful for long-running applications or applications that don't terminate and for which there is no good snapshot location or if you don't know where to place triggers.
  
Line 64: Line 63:
  
 
To use the demand framework with an enabled probe you will add <code>demand.ual</code> to the Approve command line:
 
To use the demand framework with an enabled probe you will add <code>demand.ual</code> to the Approve command line:
  <mowiki>
+
  <nowiki>
 
  aprobe -u my probe -u demand  MyApp.exe
 
  aprobe -u my probe -u demand  MyApp.exe
 
  </nowiki>
 
  </nowiki>
  
To send action commands to the probe use <code>apdemand</code> form the command line:
+
To send action commands to the probe use [[AUG_Tools_Reference#apdemand|apdemand]] form the command line:
 
  <nowiki>
 
  <nowiki>
 
  apdemand action1
 
  apdemand action1
Line 75: Line 74:
 
=== Advanced Remote Control Example ===
 
=== Advanced Remote Control Example ===
  
Remote Control is an advanced use of <code>demand.ual</code> to affect a remote application while it runs, with Aprobe and UALs, of course.  The <code>demand.ual</code> is an Aprobe predefined probe which you just include in the UAL list. To go with it, you design probes which test switches you plan to flip while the application runs.  In this case, <code>apdemand</code> will send action demands to your probes.
+
Remote Control is an advanced use of <code>demand.ual</code> to affect a remote application while it runs, with Aprobe and UALs, of course.  The <code>demand.ual</code> is an Aprobe predefined probe which you just include in the UAL list. To go with it, you design probes which test switches you plan to flip while the application runs.  In this case, [[AUG_Tools_Reference#apdemand|apdemand]] will send action demands to your probes.
  
 
In your probe APC you will define a number of boolean flags such as:
 
In your probe APC you will define a number of boolean flags such as:
Line 93: Line 92:
 
   }
 
   }
 
  </nowiki>
 
  </nowiki>
and register your callback function with a macro for the <code>apdemand</code> script:
+
and register your callback function with a macro for the [[AUG_Tools_Reference#apdemand|apdemand]] script:
 
  <nowiki>
 
  <nowiki>
 
   ap_OfferDemand(FlipOptionalOutput, "invert OptionalOutput")
 
   ap_OfferDemand(FlipOptionalOutput, "invert OptionalOutput")
 
  </nowiki>
 
  </nowiki>
then trigger callbacks while the application runs using <code>apdemand</code:
+
then trigger callbacks while the application runs using [[AUG_Tools_Reference#apdemand|apdemand]]:
 
  <nowiki>
 
  <nowiki>
 
  apdemand invert
 
  apdemand invert
Line 105: Line 104:
 
  apdemand ...
 
  apdemand ...
 
  </nowiki>
 
  </nowiki>
dynamically updates a <code>demand.cfg</code> file. It is created by the <code>ap_OfferDemand</code> macros. It is periodically read by the <code>demand.ual</code> probe within the running application. When it sees an update, it triggers your callbacks. The <code>apdemand<.code> script also manages an output "spool" file that keeps you informed about what is happening and what actions are available.  
+
dynamically updates a <code>demand.cfg</code> file. It is created by the <code>ap_OfferDemand</code> macros. It is periodically read by the <code>demand.ual</code> probe within the running application. When it sees an update, it triggers your callbacks. The [[AUG_Tools_Reference#apdemand|apdemand]] script also manages an output "spool" file that keeps you informed about what is happening and what actions are available.  
  
 
Continuing our example then, entering
 
Continuing our example then, entering
Line 115: Line 114:
 
This model can also be used to affect application output, such as sending messages, printing, and writing to files, when the application already tests switches. Your apc coding differences are minor, using $ in your probe references to an application boolean instance.
 
This model can also be used to affect application output, such as sending messages, printing, and writing to files, when the application already tests switches. Your apc coding differences are minor, using $ in your probe references to an application boolean instance.
  
A callback <code>fprintf</code> to spool is recommended. <code>FILE *spool</code> is passed to all callback functions. The file already has a spool header which identifies the callback by its registration string. The spool file is closed with a trailer when the callback function returns. Then <code>apdemand</code> sees the closing trailer and pages the spool file.
+
A callback <code>fprintf</code> to spool is recommended. <code>FILE *spool</code> is passed to all callback functions. The file already has a spool header which identifies the callback by its registration string. The spool file is closed with a trailer when the callback function returns. Then [[AUG_Tools_Reference#apdemand|apdemand]]sees the closing trailer and pages the spool file.
  
To set a number, such as a multiplier or a limit, instead of a boolean, you echo the value to a work file before triggering your callback function by <code>apdemand</code>. Your callback function opens the work file and reads the input with <code>fscanf</code>. The input value can replace or bump the controlled number.  You can also read a string from a work file, being careful about the size of the area into which you put the string.  A string pointer is safer to modify, with the input string copied to a malloc area.  You can write scripts which echo and invoke apdemand. Callbacks can also set numbers and strings in the application by echo plus demand, using $ before an application name.
+
To set a number, such as a multiplier or a limit, instead of a boolean, you echo the value to a work file before triggering your callback function by [[AUG_Tools_Reference#apdemand|apdemand]]. Your callback function opens the work file and reads the input with <code>fscanf</code>. The input value can replace or bump the controlled number.  You can also read a string from a work file, being careful about the size of the area into which you put the string.  A string pointer is safer to modify, with the input string copied to a malloc area.  You can write scripts which echo and invoke [[AUG_Tools_Reference#apdemand|apdemand]] Callbacks can also set numbers and strings in the application by echo plus demand, using $ before an application name.
  
In summary, remote controls are your design: boolean, numeric, and string data are your choices, you register phrases which <code>apdemand</code> searches for a callback function to trigger, and you write confirming feedback from your callback function.  You can write spool output from callback functions which don't change anything, and thereby design remote queries of collected probe data, or application state data. Using probes in this way, you do not interface manually with the application process.  Instead, your manual interface is with files in a remote working directory.  Your interface to change a file can be ssh commands to the application's server, or commands in a remote window on the server, or commands in any window onto shared disk, whatever works for you.
+
In summary, remote controls are your design: boolean, numeric, and string data are your choices, you register phrases which [[AUG_Tools_Reference#apdemand|apdemand]] searches for a callback function to trigger, and you write confirming feedback from your callback function.  You can write spool output from callback functions which don't change anything, and thereby design remote queries of collected probe data, or application state data. Using probes in this way, you do not interface manually with the application process.  Instead, your manual interface is with files in a remote working directory.  Your interface to change a file can be ssh commands to the application's server, or commands in a remote window on the server, or commands in any window onto shared disk, whatever works for you.
  
 
=== Usage ===
 
=== Usage ===
  
Using demand is straightforward - just include it on the Aprobe command line using the <code>-u</coce> option along with a demand-enabled probe:
+
Using demand is straightforward - just include it on the Aprobe command line using the <code>-u</code> option along with a demand-enabled probe:
 
  <nowiki>
 
  <nowiki>
 
  aprobe -u statprof -u demand myapp.exe
 
  aprobe -u statprof -u demand myapp.exe

Latest revision as of 18:05, 7 February 2019

Demand Action: demand.ual

(Since 4.4.4a)

The predefined probe demand.ual is part of a framework for "demanding" action from another probe from the command-line at nun-time, independent of what the probed program might be doing. This is an advanced feature, but can be powerful in the right circumstances.

The demand framework is integrated into a number of predefined probes (coverage, memstat, memwatch, profile, statprof) and ready to use. The demand framework can be added to custom probes as well.

The Demand Framework

The demand framework consists of the demand.h include file, the demand.ual probe, and the apdemand command-line script.

The apdemand command is your way of requesting action.

The demand UAL needs to be included in Aprobe runs by -u demand, because it is a pre-defined UAL whose logic you can ignore.

The ap_OfferDemand() macro is invoked in the UAL APC files. You only need to look at the macro to write custom APC which offers your own actions on-demand. The macro is in $APROBE/include/demand.h, and an example of its use is at the end of $APROBE/probes/profile.apc.

Actions On-Demand From Predefined UALs

Several predefined UALs offer snapshots and other actions on user demand:

  • coverage.ual
  • memwatch.ual
  • memstat.ual
  • profile.ual
  • statprof.ual

Demand snapshots are logged like snapshots you can trigger by naming trigger functions in the config files, but demand needs no internal triggers. Instead, the trigger is a command you can enter from any shell using apdemand. This may be useful for long-running applications or applications that don't terminate and for which there is no good snapshot location or if you don't know where to place triggers.

See the documentation for those probes to see available demand actions.

Simple Probe Example

A probe can be enabled for the demand framework by including the demand.h file and then instantiating the ap_OfferDemand() macro to define actions which can be demanded from the command line. The ap_OfferDemand() macro defines the action name and a callback to perform the action.

Here is an example of that:

 #include "demand.h"
 
 ...

 void MyActionCallback(FILE *spool)
 {
    // write to the demand spool file to provide status 
    fprintf(spool "starting my action...\n");

    // performs the action
    DoSnapshot();

    // write to the demand spool file to provide status
    fpritnf(spool, "dons my action\n");
 }

 ap_OffserDemand(MyActionCallback, "myprobe action1");
 

To use the demand framework with an enabled probe you will add demand.ual to the Approve command line:

 aprobe -u my probe -u demand  MyApp.exe
 

To send action commands to the probe use apdemand form the command line:

 apdemand action1
 

Advanced Remote Control Example

Remote Control is an advanced use of demand.ual to affect a remote application while it runs, with Aprobe and UALs, of course. The demand.ual is an Aprobe predefined probe which you just include in the UAL list. To go with it, you design probes which test switches you plan to flip while the application runs. In this case, apdemand will send action demands to your probes.

In your probe APC you will define a number of boolean flags such as:

:
 ap_BooleanT OptionalOutputWanted = FALSE;
 

You also put the output code inside a conditional like:

 if (OptionalOutputWanted) { ... }
 

And, finally, you declare an action callback function to set the flag:

  void FlipOptionalOutput(FILE *spool) 
  {
     OptionalOutputWanted = ! OptionalOutputWanted;
     fprintf(spool, "OptionalOutputWanted is %d\n", OptionalOutputWanted);
  }
 

and register your callback function with a macro for the apdemand script:

  ap_OfferDemand(FlipOptionalOutput, "invert OptionalOutput")
 

then trigger callbacks while the application runs using apdemand:

 apdemand invert
 

From a separate, usually remote command shell, entering

 apdemand ...
 

dynamically updates a demand.cfg file. It is created by the ap_OfferDemand macros. It is periodically read by the demand.ual probe within the running application. When it sees an update, it triggers your callbacks. The apdemand script also manages an output "spool" file that keeps you informed about what is happening and what actions are available.

Continuing our example then, entering

 apdemand nal

triggers callbacks which contain "nal" in the registration string. You can have many switches and callback functions, each registered with a meaningful phrase in quotes. You can trigger one at a time, or several at once, by choosing a unique string fragment, or a string fragment which occurs in several registrations. Planning ahead is useful.

This model can also be used to affect application output, such as sending messages, printing, and writing to files, when the application already tests switches. Your apc coding differences are minor, using $ in your probe references to an application boolean instance.

A callback fprintf to spool is recommended. FILE *spool is passed to all callback functions. The file already has a spool header which identifies the callback by its registration string. The spool file is closed with a trailer when the callback function returns. Then apdemandsees the closing trailer and pages the spool file.

To set a number, such as a multiplier or a limit, instead of a boolean, you echo the value to a work file before triggering your callback function by apdemand. Your callback function opens the work file and reads the input with fscanf. The input value can replace or bump the controlled number. You can also read a string from a work file, being careful about the size of the area into which you put the string. A string pointer is safer to modify, with the input string copied to a malloc area. You can write scripts which echo and invoke apdemand Callbacks can also set numbers and strings in the application by echo plus demand, using $ before an application name.

In summary, remote controls are your design: boolean, numeric, and string data are your choices, you register phrases which apdemand searches for a callback function to trigger, and you write confirming feedback from your callback function. You can write spool output from callback functions which don't change anything, and thereby design remote queries of collected probe data, or application state data. Using probes in this way, you do not interface manually with the application process. Instead, your manual interface is with files in a remote working directory. Your interface to change a file can be ssh commands to the application's server, or commands in a remote window on the server, or commands in any window onto shared disk, whatever works for you.

Usage

Using demand is straightforward - just include it on the Aprobe command line using the -u option along with a demand-enabled probe:

 aprobe -u statprof -u demand myapp.exe