ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / appstat / !APPstat / !Help next >

Wrap

Text File | 1998-06-07 | 13.8 KB | 304 lines

Application Statistics ====================== Documentation for !APPstat application version 1.10 07-Jun-1998 for RISC OS 3.1 and later. Issue: 1.10 07-Jun-1998, replaces: 0.10 03-May-1995 0.90 28-May-1995 0.99 17-Jun-1995 Author: David J Ruck Copyright © DEEJ Technology PLC 1995-8 Overview ======== The !APPstat application provides information on the activity of all running RISC OS application in your machine, it is the best tool available for ensuring that your WIMP programs are fast and efficient. It is intended for programmers who wish to debug or improve the efficiency of their applications. It does this by showing exactly which WIMP events are being delivered to each application, in what quantity, and how long the application takes to process them. It can also be used by the merely incurably curious for a fascinating insight into what the computer is getting up to, and which tasks are hogging the CPU. Using !APPstat ============== When started !APPstat installs its own icon on the icon bar, clicking on it will display the main window. This window contains information on all applications that are active at the current time. Each running application has its own entry, giving its name, a value and a graphic display of this value, similar to the bars used in the Task manager's window. The value is one of four types, the number of calls to the application or the time spent in the application, either as a total value or the value occurring over a definable time interval. Switching between these displays is described in the !APPstat menu section below. The Main Window The first entry in the window is the total value of all the entries below corresponding to the time between updates of the display. The next two bars display the system overhead and the totals for all applications. The system overhead is the time the WIMP spends in the WIMP_Poll SWI. When displaying call counts all three bars have the same value, corresponding to the number of calls made to all applications. The bars below correspond to the call/times for each running application. Clicking on All Applications any of the application names will display a subwindow for that application. The All Applications subwindow shows the combined information for every running application. Any new applications which are started while !APPstat is run are added to the end of the main window. Sub Windows The subwindows for each application are similar to that of the main window, except that the number of calls or timings for each WIMP event and message that the application receives are displayed. The first entry is the total for that application, as is displayed in the main window. The next twenty entries correspond to each of the event codes returned by the Wimp_Poll SWI. The remaining entries in the window are the calls/timings for each type of message delivered to the application on event types 17 and 18 (Send Message and Send Message Want Ack). Messages returned by event 19 (Acknowledge Message) are not counted by these bars. Events and messages, which are recognised by the program are assigned names, others will be displayed as a numbers. Most common message types are already displayed, others will be added to the window when they occur. Counter Windows Clicking on the Applications & System, or System Overhead entries in the main window or any entry in a subwindow will call up a counter window. The counter window shows the number of calls or the time spent processing (an individual event/message or the total for an application) occurring in the set interval, as a vertical line. The display scrolls to the left each interval to show a new value, thus the variation in activity of a application can be monitored over a period of time. It is easier to see sudden peaks of activity in a counter window than in the main and subwindows, which do not need to be open once a counter window has been called up. Any number of counter windows (memory permitting) can be active at once. The counter window display automatically scales up and down to fit the maximum value in the window. At the default scale 4 OS units (1 rectangular pixel) is equivalent to one call or 1µs, each subsequent scale is half the last shown by the horizontal grey lines. These do not represent values but show how many times the height of the bars have been halved; e.g. 1 line = ½ scale, 2 lines = ¼ scale, 10 lines 1/1024th scale. Window menu ----------- The main window and all subwindows provide a menu, the entries are described below. Totals This affects the main window and all subwindows. When ticked the display of each window gives the number of calls or time spent processing for each application or WIMP event since !APPstat was started (or Zero counts was used). Per interval This also affects the main window and all subwindows; it changes the displays to show the number of calls / time spent over a given time interval, set by Update rate below. The dark grey window titles changes to show the desired rate, and in brackets, the actual rate achieved in milliseconds. Call Counts This option effects the main window, all subwindows and all counters currently displayed. When ticked the number of calls to each application or for each WIMP event/message will be displayed in the windows. Timings When ticked all windows and counters will display the time the applications spend processing each WIMP event/message. The timings are displayed in seconds, with the factional value accurate to the nearest microsecond. Update rate The value entered into the writable sub menu determines the interval used when displaying in Per interval mode, and the update rate of counter windows, which always show the number of calls/timings during this interval in both Totals and Per interval modes. The value entered is in milliseconds (1/1000th sec), due to RISC OS limitations it is only possible to set the rate to the nearest 10ms, a minimum of 100ms is imposed. When using large values it should be noted that the new value only comes into effect on the next scheduled update. If a lot of tasks are running or a number of subwindows or counter windows are open it may not be possible for the program to update its displays at very high rates, this is automatically taken into account, and the values and sizes of bars are corrected accordingly. Scale Bars in the main and subwindows are automatically scaled to fit the largest in the window by default, this can however, lead to the bars for small values disappearing. Clicking on the Scale option on the main menu toggles automatic and manual scaling, which is shown by a tick next to scale. When using manual scaling values can be entered in the writable submenu, integer and fractional values are allowed. Iconbar menu ------------ Info Displays program information and version number. Display Displays the main window, equivalent to clicking on the !APPstat icon. Kill Quits the application and kills the APPmod module which performs the counting and timing monitoring of applications. This ensures the small processing overhead imposed by the module is removed. Quit Quits the application, the APPmod module is not killed so if the program is run again, the application counts and timing totals will still have been incremented while the program was not running, see Technical details below. Technical details ================= !APPstat works by loading a special module APPmod which installs WIMP pre and post–filters to enable the module to recognise when an application has been switched in by the WIMP. The post–filter enables the type of event that is being delivered to the application to be extracted and separate counts and timings held for each. The timings are obtained by reading the IOC timer 0 and the monotonic system clock (which is incremented by the timer 0 events). The timer and clock values are combined to produce a second and microsecond time value. The details below are provided for users who may wish to use this module in their own programs. Note: The SWI chunk number for APPmod is currently provisional and will change on receiving official Acorn registration. APP_stat !APPstat uses this call every update interval to (&C4580 provisional) read the current APP call counts and timing information, and calculate the correct values for the program displays. A call to APP_stat (no parameters required) returns a pointer in R0 to a memory structure (type: main_str) which is described in C as: typedef struct { struct app__str *chain_ptr; /* pointer to chain of app_str */ timeval sys_time; /* total of system execution time */ } main_str; typedef struct app__str { struct app__str *next_ptr; /* pointer to next in chain */ wimp_t task; /* task handle of application */ stat_str app_total; /* total count/time for this app */ stat_str events[20]; /* counts/time for wimp events */ msgstat_str messages[256]; /* counts/time for 256 messages */ } app_str; typedef struct { wimp_msgaction action; /* message action or -1 not used */ stat_str info; /* count/time for message type */ } msgstat_str; typedef struct { long count; /* numbers of calls for item */ timeval time; /* total run time for item */ } stat_str; typedef struct { long tv_sec; /* time in seconds */ long tv_usec; /* microsecond excess */ } timeval; The main_str chain_ptr points to a list of app_str for each application, terminated by a 0 in next_ptr of the last app_str. The first app_str in the list has a task handle of -1 and corresponds to All Applications combined totals. Only some of the 256 possible messages entries are assigned to valid message action types initially. The msgstat_str action field contains -1 if the entry is not assigned. Further entries are assigned on receipt of new message types. APP_Zero Calling this routine causes all the counts and (&C4581 provisional) timings to be zeroed. Counting continues immediately. APP_Control This call is used to activate (R0 = 1) or suspend (&C4582 provisional) (R0 = 0) the modules counting and timing activity. While suspended the WIMP filters are still enabled, but computational overhead of the counting and timing operations are removed. Changes ======= 1.10 Known message list updated. Unknown message numbers named after module SWI chunks if appropriate. !SWIstat ======== Also from DEEJ Technology PLC is the companion application !SWIstat. Using the same style of displays !SWIstat provides information on the activity of all SoftWare Interrupts (SWI's) occurring in your machine, the next best thing to Acorns own hardware debugging systems. It is intended for programmers who wish to debug or improve the efficiency of their application's or module's interface with the OS. It does this by showing exactly which software interrupt calls are being made, when and in what quantity. !SWIstat can monitor SWI activity from all applications running in the machine, or just a chosen one, enabling scrutiny of a particular application under test. All tasks except !SWIstat can be monitored to partially remove the effect of running the application in a development environment. End of APPstat User Guide.