!JustAHack

(playing with the TaskWindow module in the Wimp) Current release is v0.2
Author: Benoît GILON

Overview

!JustAHack is a sample application which demonstrates how WIMP programs can use the Acorn TaskWindow module in RO3 and later OS releases.
Through it is not the article which I planned to submit to CAUGers for the second issue of the Multi-threading series (hence the name !JustAHack). It is not completely disjointed from the topics discussed herein.
!JustAHack is a WIMP based application (more precisely Acorn Toolbox based) which:

launches separate tasks under the control of the TaskWindow module;
updates some of its toolbox graphic gadgets according to the output generated by the newly created tasks.
gives the user the ability to suspend/resume or kill a then launched taswindow task;

!JustAHack is just a sample application, my goal here is not to provide readers with a complete ready to use library for them to build their own applications. A bit more work is needed to handle this project.
If a reader is interested by the subject and could invest some of his (spare) time in it, then a direction to investigate is how feasible is a Wimp based application which renders toolbox gadgets in name of taskwindow tasks (like a frontend).

!JustAHack User guide

!JustAHack is a convenient application for measuring relative performance of sort algorithms over text files. When you run !JustAHack, it installs an icon on the iconbar. From then on, you can drag multiple text files onto the icon: for each file dragged upon it, !JustHack will open a window similar to the one below: Main !JustAHack window

The number to the right of the progress bars is the number of lines in the file (here 647);
To start the sorts (which are performed by taskwindow processes), just click on the "Sort" action button;
From then on, the user will see the progress bars being updated as the sorts take place;
He can suspend one process by clicking on the relevant "Suspend" action button (which has been unfaded inbetween);
He can also kill a child taskwindow task by clicking the "Kill" action button (unfaded too as soon as the user clicked on the "Sort" action button).

A "funny" thing to try out is to drag plenty (well about 4 ;-) otherwise your desktop will become a bit messy at least on a VGA display) of files to the !JustAHack iconbar icon; and then select the "Parallel run" entry in the iconbar menu, thus acting as if you clicked to the "Sort" action button of every application's open window; Recommended "companion applications" to activate while running !JustAHack are:

!Usage (to see the workload per Wimp task) by Ran Mokady, v1.00 (24 May 90)
!WimpMon by Tom Hughes v1.35 (23 Sep 95) to track Wimp message traffic;

How it works

JAHSupport module

In order to supply multiple dynamically created taskwindow process w/o overloading the media support with I/O, I designed a module named JAHSupport which provides five commands:

JAHLoadFile <key> <pathname>: Load a datafile in RMA and assign a key value to its content for future reference; the current release will not read further than the first 1024 text file physical lines. The output (standard output stream) from this command is simply the number of lines read in memory from the file (it is then redirected to the parent task via the TaskWindow messaging mechanism)
JAHQSort <key> [limit], JAHBSort <key> [limit], JAHSSort <key> [limit]: Sorts a datafile in memory (the result of the sort is discarded): three algorithms are provided hence three commands; The output from those commands is a list of lines which marks the progress of the sort algorithm (# of lines already processed); the optional limit parameter allows for filtering the output of such sorting, thus reducing the time for the sort to complete.
JAHUnLoadFile <key>: Tells the module to discard memory resources allocated for a specific datafile load;

There is no SWI, No IRQ handler.
Making the datafile load from the compute step separate, the mechanism for applying concurrently multiple sorts is much easier and much more efficient.

JAH Wimp application

!JustAHack includes features which first appeared in my !TopTen program (v0.6.5); For every file dragging upon the !JustAHack icon, the application creates the structure below in memory:

#define NUMBER_SORT_ALGO 3
enum    {
        KBUBLE = 0, KQUICK, KSELECT, KLOAD
        };
/* The "tclient" structure serves for managing the communication with a
   taskwindow child task */
typedef struct
        {
        int twcid; /* wimp task handle of the taskwindow task */
        int issuspended; /* is it currently suspended? */
        /* Toolbox components upgradable according to the output
           of such taskwindow task*/
        ComponentId pgbcid, dispcid, srcid, killtcid;
        /* "Status" of the taskwindow child task */
        enum    {
                INITIAL= 0 /* WAITING FOR CIDLOAD */,
                WAITFORCR /* WAITING FOR NR */,
                LOADED
                } status;
        } tclient;
typedef struct
        {
        struct MinNode mnode; /* used for chaining the structure as a node */
        int key; /* external ID used for submitting requests to the module */
        size_t nbusy; /* # of child tasks active */
        tclient client[NUMBER_SORT_ALGO+1];
        /* Acorn Toolbox objectid for this window */
        ObjectId woid;
        /* Complete pathname for the file being "processed" */
        char fname[FILENAME_MAX+1];
        } filestruct;

The dynamic behavior of the application could be described by the diagrams below which shows the the many steps performed upon a user action or as an external (outside the Wimp application) event occurs: Dynamic behavior for !JustAHack

Note: if you find the diagram above difficult to read, then note that the original Drawfile is included in the !JustAHack source archive downloadable from the !JustAHack main page.

A point of interest is also how !JustAHack implements the "parallel run" feature: here is the callback function called as the user clicks on the "Parallel run" entry in the iconbar menu.

static int parallelrun_event(int event_code,
        ToolboxEvent *event, IdBlock *id_block, void *handle)
{
const ActionButtonSelectedEvent monevent = {
        { 16, 0, ActionButton_Selected, ActionButton_Selected_Default }
        };
struct MinNode *pw;
filestruct *pf;
/* Examine every file structure in the chain */
for(pw= mafilelist.mlh_Head; pw->mln_Succ; pw= pw->mln_Succ)
        {
        /* Compute structure base address from one of its fields' address */
        pf= (filestruct *) ((char *) pw - offsetof(filestruct, mnode));
        /* Only if Sort button is unfaded */
        if(pf->nbusy == 0 && pf->client[KLOAD].status== LOADED)
                /* Raise a toolbox event */
                (void) toolbox_raise_toolbox_event(0,
                        pf->woid, KACTBUTSRT, (ToolboxEvent *) &monevent);
        }
return 1;
}

Final notes

Behavior of the Acorn Taskwindow module

One quest I followed during the program design was to determine at what time exactly the Acorn TaskWindow module sends a TaskWindow_Output message to the parent task, according to the amount of output data pending (having been sent by the TaskWindow child task). I found out that the kind of buffering done is full buffering but with a buffer size around 126 which is approximately half the available room size in a TaskWindowOutput WIMP message. As it is required that my parent task be advised ASAP of the progress reached by a taskwindow child task, all the output from those tasks have the format below:

0 '*'
1:10 progress indicator (right justified)
11:124 ' ' (space character)
125 '\n'

Thus, I am sure that one indicator value is directly converted to one Wimp message.

Evaluating how generated output affect performance and about balancing sort process

Since the v0.2 release of !JustAHack, the Messages file hold three new entries

LIMITQ (Quick)
LIMITB (bubble)
LIMITS (Select)

which contain the limit parameter provided to the JAHSupport module's sort command. For a given sort algorithm, the greater is this value, the less ouput is generated by relevant processes and the less time they take to complete.