About Triggers

What Are Triggers?

Triggers are an AQTime facility allowing for better control of profiling under the Performance, Coverage and Function Trace profilers. The purpose of triggers is to allow profiling to come on when certain routines (on-triggers, see below) are executing (including during their calls to “child” routines), or on the contrary to be turned off (off-triggers, see below). Do not confuse triggers with areas, the purpose of using them differs. With areas and checking, you set what you never want profiled during the current run (that is, everything but the checked elements). With triggers and Initial Status, you set in what part of the execution path you want to enable profiling, or to disable it.

The list of triggers are defined in the Triggers and Actions pane of the Setup panel and include three linked settings: on-triggers, off-triggers and Initial profiling status for Threads.

Initial Profiling Status for Threads is one default trigger displayed at the top of the Triggers list. It sets the profiling status at the beginning of threads, before any other triggers click it (after that, it has no effect). Initial profiling status can be set on (profiling allowed until an off-trigger operates) or off (no profiling until an on-trigger operates).

Other triggers in the list are collections of potential trigger routines of one type, either on- or off-.

Besides the trigger type, you can also specify additional options for triggers:

• Except for the Initial Status trigger, each trigger can be tuned regarding after how many calls a trigger will start operating, and then for how many calls (after which it will become inoperative). These two options are themselves affected by another option - is the call count taken over all threads, or over each thread individually? This yes-no option, which sets the meaning of the ones explained below, is For All Threads. Remember that, whether or not calls are counted over all threads, triggers only act on their own thread.
• The Pass Count option allows the trigger routine or routines to be called a certain number of times before they act as triggers. For instance, this lets you skip the startup phase of your application. Pass Count 3 means “only act as trigger on the fourth call”. By default Pass Count is 0 and operates from the first call.
• The Work Count option then sets how many consecutive calls will act on the trigger (to allow profiling or to disallow it), before the trigger stops acting again. This is a way to limit the amount of data gathered at the point where it just repeats what’s known. 0 is again the default, but here it does not mean “never activate”, it means “stay activated to end of run”.
• Finally, the Cycling yes-no option (default no) sets whether the pass-count-work-count cycle will repeat after work count + 1 is reached and the trigger is deactivated. A cycling trigger is a way to sample application behavior through various phases without amassing data for every single call.

For more information on how to create triggers and how to set their options, see Creating, Editing and Deleting Triggers.

No triggers operate at all unless at least one collection is checked. And in the collection only those triggers operate which are checked also. The mechanism of enabling/disabling actions is identical to that of checking areas' elements. For details, see Checking Elements to Profile.

Some notes about triggers:

• A “trigger” collection is defined as holding on- or off- triggers (one type per collection), not just triggers.
• Of all means of selecting what to profile, triggers are the only one that can select on a thread basis.
• Triggers work in conjunction with the other means of selecting what to profile. Execution is actually profiled only when all means say “yes”. For example, no matter what triggers and Initial Status may decree, nothing will get profiled if it is not checked in the areas section. For more information, see Controlling What to Profile.
• AQTime treats routines added to a trigger as routines added to an area. This is not dependent on the trigger type (on or off). The profiling level depends on whether the routine belongs to any area:
  • If the routine is not added to any area, it will be profiled at routine level.
  • If the routine belongs to a line-level or routine-level area, it will be profiled at line level or routine level correspondingly.
  • If the routine belongs to an excluded area, it will still be profiled at routine level. That is, trigger routines cannot be excluded from profiling.

How Triggers Work

Technically, what triggers do is very simple to explain:

• For any given thread, at any given moment, profiling status is “enabled” or “disabled”. Profiling actually operates in a thread if, one, status for that thread is “enabled” and, two, nothing else excludes the current routine from profiling.

• The Enable/Disable Profiling buttonThe AQTime > Enable/Disable Profiling menu itemThe AQTime > Enable/Disable Profiling menu item is an onscreen way of controlling profiling status by hand while the application runs. If it is pressed-in (), profiling status is as set otherwise. When you unclick it (), profiling is turned off for all threads. When you press it back in, you re-enable profiling, according to whatever is otherwise set for the application at that point (not as it was when you disabled it).

• If there are triggers of any kind, the Initial Profiling Status for Threads option specifies whether the profiling on or off on the creation of each new thread. In other words, Initial Profiling Status defines whether profiling is enabled or not before any trigger in a thread starts executing. After that, it has no effect. Likewise if there are no triggers at all.

• When an on-trigger routine begins executing, it saves the current profiling status for its thread and enables profiling for that thread. This still applies to everything it calls. When it reaches the end of its execution (after perhaps hundreds of calls, sub-calls and sub-sub-calls), it restores the thread’s profiling status as it found it.

• When an off-trigger routine begins executing, it saves the current profiling status for its thread and turns profiling off for that thread. When it reaches the end of its execution, it restores the thread’s profiling status as it found it.

Suppose, Proc_B is an off-trigger routine, profiling is currently enabled and either All Project Modules (Routines only) or All Project Modules (Collect info about lines) is used:

As profiling is enabled and All Project Modules is on, AQTime profiles Proc_A. When the application enters Proc_B, profiling is disabled for that thread. So Proc_D and Proc_E are not profiled. When Proc_B exits, AQTime restores the profiling status as it was -- enabled -- so Proc_C is profiled.

See Also

Creating, Editing and Deleting Triggers
Controlling What to Profile
About Actions