[Cyan]<Gargoyle>SlackProcessImpl.mesa!14

SlackProcessImpl.mesa

Last edited by Pier on November 5, 1986 7:05:50 pm PST

Bier, February 9, 1987 6:43:54 pm PST

DIRECTORY

Atom, CedarProcess, IO, Process, Rope, SlackProcess, TIPUser, Terminal, TerminalDefs, Interminal, ViewerClasses, ViewerOps;

SlackProcessImpl: CEDAR MONITOR LOCKS handle USING handle: SlackHandle

IMPORTS Atom, CedarProcess, IO, Process, Terminal, Interminal, ViewerOps

EXPORTS SlackProcess = BEGIN

SlackProcess solves a problem in user interfaces that employ smooth motion. For instance, in Gargoyle and Solidviews, the user can move objects smoothly by moving the mouse. Problem: how often should the frames be redrawn? The easiest solution to implement is to redraw the scene once for each mouse motion action from the TIP table. Unfortunately, for complex frames, this results in the redrawing getting behind the user. A simple improvement, suggested years ago by Scott McGregor, is to queue up the TIP table actions, and provide a second process, the slack process, to dequeue and execute them. If the slack process gets behind, it drops some actions on the floor in order to catch up. Thus the motion is "as smooth as possible" but doesn't get behind. Scott points out that, as more processing power becomes available, this algorithm allows motion to get smoother without recoding.

The name SlackProcess refers to the user's perception, with the naive algorithm, that the objects he is dragging are lagging farther and farther from the cursor, like a dog with too long a leash.

SlackProcess also serves to synchronize user actions. There is no need to use MBQueues and similar packages if SlackProcess is used.

Multiple slack processes and their associated queues may be used by many clients; the slack process issues a handle containing MONITORED data for use by the client. Actions may be queued by calls to QueueInputAction or QueueInputActionWithPoint.

Each SlackProcess provides a logging feature for clients. A client can register a Logging procedure and enable/disable Session logging. With logging enabled, the registered Logging procedure will be called every time an action is dequeued. The client may then save a log or script of the session in progress for later playback to a future SlackProcess.

Each SlackProcess provides an abort feature for clients. A client can register an Abort procedure and some abort data and enable/disable aborting. With aborting enabled, the slack queue will be flushed and the registered abort procedure will be called (with the abort data as argument) every time an abort occurs. The current trigger for the abort action is holding down SHIFT-SWAT (SHIFT-Spare3) on a Dorado with the cursor in the viewer to be aborted. If the viewer specified when aborting is registered is NIL, then the cursor position will be ignored when checking for abort.

BEGIN CODE

AbortData: TYPE = SlackProcess.AbortData;

AbortProc: TYPE = SlackProcess.AbortProc;

Actions: TYPE = SlackProcess.Actions;

ActionsData: TYPE = SlackProcess.ActionsData;

BashedData: TYPE = SlackProcess.BashedData;

ClientDatas: TYPE = SlackProcess.ClientDatas;

ClientDatasData: TYPE = SlackProcess.ClientDatasData;

EventProc: TYPE = SlackProcess.EventProc;

EventProcs: TYPE = SlackProcess.EventProcs;

EventProcsData: TYPE = SlackProcess.EventProcsData;

EventsData: TYPE = SlackProcess.EventsData;

Log: TYPE = SlackProcess.Log;

LogData: TYPE = SlackProcess.LogData;

LoggingProc: TYPE = SlackProcess.LoggingProc;

MouseEventProc: TYPE = SlackProcess.MouseEventProc;

MouseProcs: TYPE = SlackProcess.MouseProcs;

MouseProcsData: TYPE = SlackProcess.MouseProcsData;

OptimizeProc: TYPE = SlackProcess.OptimizeProc;

OptimizeHints: TYPE = REF OptimizeHintsData;

OptimizeHintsData: TYPE = SlackProcess.OptimizeHintsData;

Point: TYPE = SlackProcess.Point; -- RECORD [x, y: REAL]

Points: TYPE = SlackProcess.Points;

PointsData: TYPE = SlackProcess.PointsData;

Queue: TYPE = SlackProcess.Queue;

QueueData: TYPE = SlackProcess.QueueData;

QueueEntryGenerator: TYPE = REF QueueEntryGeneratorObj;

QueueEntryGeneratorObj: TYPE = SlackProcess.QueueEntryGeneratorObj;

ReceivedData: TYPE = SlackProcess.ReceivedData;

Viewer: TYPE = ViewerClasses.Viewer;

SlackData: PUBLIC TYPE = SlackProcess.SlackData; -- this is the monitored record type

SlackHandle: TYPE = REF SlackData;

Problem: PUBLIC ERROR[msg: Rope.ROPE] = CODE;

NoOptimization: OptimizeProc = { -- do all of the actions on the queue

skipActions ← 0;

};

Creating a SlackProcess

Create: PUBLIC PROC [queueSize: NAT ← 50, logSize: NAT ← 50, optimizeProc: OptimizeProc, loggingProc: LoggingProc ← NIL, abortProc: AbortProc ← NIL, abortData: REF ANY ← NIL, abortViewer: ViewerClasses.Viewer ← NIL] RETURNS[handle: SlackHandle] = {

handle ← NEW[SlackData ← [slackProcess: NIL, queue: NEW[QueueData ← [] ], qeGen: NEW[QueueEntryGeneratorObj], log: NEW[LogData ← [] ], abort: NEW[AbortData ← [] ] ] ];

handle.queue.clientDatas ← NEW[ClientDatasData[queueSize]];

handle.queue.optimizeHints ← NEW[OptimizeHintsData[queueSize]];

handle.queue.actions ← NEW[ActionsData[queueSize]];

handle.queue.points ← NEW[PointsData[queueSize]];

handle.queue.mouseProcs ← NEW[MouseProcsData[queueSize]];

handle.queue.eventProcs ← NEW[EventProcsData[queueSize]];

handle.queue.size ← queueSize;

IF optimizeProc = NIL THEN handle.optimizeProc ← NoOptimization

ELSE handle.optimizeProc ← optimizeProc;

handle.log.received ← NEW[ReceivedData[logSize]];

handle.log.bashed ← NEW[BashedData[logSize]];

handle.log.events ← NEW[EventsData[logSize]];

handle.log.points ← NEW[PointsData[logSize]];

handle.log.size ← logSize;

handle.log.logger ← loggingProc;

handle.abort^ ← [enabled: FALSE, viewer: abortViewer, proc: abortProc, data: abortData];

};

Queuing Actions

QueueInputActionWithPoint: PUBLIC ENTRY PROC [handle: SlackHandle, callBack: MouseEventProc, inputAction: LIST OF REF ANY, point: Point, clientData: REF ANY, optimizeHint: REF ANY] = TRUSTED {

Add an action to the tail of the slack process queue. Process.Detach is an unsafe operation.

ENABLE UNWIND => NULL;

queue: Queue ← handle.queue;

qIndex: NAT ← 0;

WHILE (queue.tail+1) MOD queue.size = queue.head DO WAIT queue.notFull ENDLOOP;

qIndex ← queue.tail;

queue.clientDatas[qIndex] ← clientData;

queue.optimizeHints[qIndex] ← optimizeHint;

queue.actions[qIndex] ← inputAction;

queue.points[qIndex] ← point;

queue.mouseProcs[qIndex] ← callBack;

queue.eventProcs[qIndex] ← NIL;

queue.tail ← (qIndex + 1) MOD queue.size;

LogReceived[log: handle.log, event: inputAction.first, point: point, bash: FALSE];

IF handle.slackProcess = NIL THEN Process.Detach[handle.slackProcess ← FORK Actor[handle]];

};

QueueInputAction: PUBLIC ENTRY PROC [handle: SlackHandle, callBack: EventProc, inputAction: LIST OF REF ANY, clientData: REF ANY, optimizeHint: REF ANY] = TRUSTED {

Add an action to the slack processes queue. Process.Detach is an unsafe operation.

ENABLE UNWIND => NULL;

queue: Queue ← handle.queue;

qIndex: NAT ← 0;

WHILE (queue.tail+1) MOD queue.size = queue.head DO WAIT queue.notFull ENDLOOP;

qIndex ← queue.tail;

queue.clientDatas[qIndex] ← clientData;

queue.optimizeHints[qIndex] ← optimizeHint;

queue.actions[qIndex] ← inputAction;

queue.points[qIndex] ← [-9999.0, -9999.0];

queue.mouseProcs[qIndex] ← NIL;

queue.eventProcs[qIndex] ← callBack;

queue.tail ← (qIndex + 1) MOD queue.size;

LogReceived[log: handle.log, event: inputAction.first, point: [-9999.0, -9999.0], bash: FALSE];

IF handle.slackProcess = NIL THEN Process.Detach[handle.slackProcess ← FORK Actor[handle]];

};

Restarting a SlackProcess that has been ABORTed (e.g. from an ERROR window).

Restart: PUBLIC ENTRY PROC [handle: SlackHandle] = TRUSTED {

Sometimes the Painter process is aborted because of a bug in one of the dispatched procedures. This procedure allows the user to get things going again.

ENABLE UNWIND => NULL;

Process.Detach[handle.slackProcess ← FORK Actor[handle] ];

};

Cancelling all actions on the queue.

FlushQueue: PUBLIC ENTRY PROC [handle: SlackHandle] = {

ENABLE UNWIND => NULL;

FlushQueueInternal[handle];

};

FlushQueueInternal: INTERNAL PROC [handle: SlackHandle] = {

Removes all unprocessed actions from the slack queue. CAUTION: If the caller is counting on a certain set of actions to be done atomically, this call could destroy its invariants.

queueSize: NAT ← handle.queue.size;

FOR i: NAT IN [0..queueSize-1] DO

handle.queue.clientDatas[i] ← NIL;

handle.queue.optimizeHints[i] ← NIL;

handle.queue.actions[i] ← NIL;

handle.queue.points[i] ← [0,0];

handle.queue.mouseProcs[i] ← NIL;

handle.queue.eventProcs[i] ← NIL;

ENDLOOP;

handle.queue.head ← 0;

handle.queue.tail ← 0;

BROADCAST handle.queue.notFull;

};

Utilities

PeekActionTail: INTERNAL PROC [queue: Queue] RETURNS [whatToDo: ATOM] = {

IF queue.head = queue.tail THEN RETURN[NIL];

whatToDo ← NARROW[queue.actions[(queue.tail - 1 + queue.size) MOD queue.size].first, ATOM];

};

Actor: PROC [handle: SlackHandle] = { -- runs in autonomous process(es) to service queue(s)

May FORK a process that looks to see if SHIFT-SWAT is down and aborts Actor if it is.

IF handle.abort.enabled THEN [] ← CedarProcess.Fork[Killer, handle, [excited, TRUE]];

DoActorsJob[handle ! UNWIND => NilIt[handle]];

NilIt[handle];

};

NilIt: PRIVATE ENTRY PROC [handle: SlackHandle] = TRUSTED {handle.slackProcess ← NIL};

Killer: PROC [data: REF] RETURNS [results: REF ← NIL] = {

handle: SlackHandle ← NARROW[data];

UNTIL handle.slackProcess = NIL DO

IF MaybeKill[] THEN handle.abort.proc[handle.abortData]; -- WHERE TO DO THIS ??

[] ← MaybeKill[handle];

Process.Pause[ticks: Process.SecondsToTicks[1]];

ENDLOOP;

};

MaybeKill: PRIVATE ENTRY PROC [handle: SlackHandle] RETURNS [killed: BOOL ← FALSE]= {

ClientWantsKill: PROC RETURNS [killIt: BOOL ← FALSE] = {

mouse: Interminal.MousePosition;

tsc: TIPUser.TIPScreenCoords ← NEW[TIPUser.TIPScreenCoordsRec];

vt: Terminal.Virtual ← Terminal.Current[];

keyBits: Terminal.KeyBits ← Terminal.GetKeys[vt: vt];

killBits: BOOL ← (keyBits[LeftShift]=down OR keyBits[RightShift]=down) AND keyBits[TerminalDefs.Spare3]=down;

IF killBits THEN {

IF handle.abort.viewer=NIL THEN RETURN[TRUE]; -- viewer does not matter

mouse ← Interminal.GetMousePosition[];

tsc^ ← [

mouseX: mouse.mouseX,

mouseY: (IF mouse.color THEN vt.colorHeight ELSE vt.bwHeight) - mouse.mouseY,

color: mouse.color

];

RETURN[ViewerOps.MouseInViewer[tsc: tsc].viewer=handle.abort.viewer];

};

IF handle.slackProcess#NIL AND ClientWantsKill[] THEN TRUSTED {

Process.Abort[handle.slackProcess]; -- kill the actor slack process

handle.slackProcess ← NIL;

FlushQueueInternal[handle]; -- you have to do this HERE holding the handle lock!

IF handle.abort.proc#NIL THEN handle.abort.proc[handle.abort.data]; -- notify the user that abort happened. Hold the lock.

RETURN[TRUE];

};

DoActorsJob: PROC [handle: SlackHandle] = { -- autonomous process(es) to service queue(s)

inputAction: LIST OF REF ANY;

point: Point;

clientData: REF ANY;

mouseEventProc: MouseEventProc;

eventProc: EventProc;

[mouseEventProc, eventProc, inputAction, point, clientData] ← NextAction[handle];

WHILE inputAction # NIL DO

IF mouseEventProc = NIL THEN eventProc[inputAction, clientData]

ELSE mouseEventProc[inputAction, point, clientData];

[mouseEventProc, eventProc, inputAction, point, clientData] ← NextAction[handle];

ENDLOOP;

};

EmptyQ: INTERNAL PROC [queue: Queue] RETURNS [BOOL] = {

RETURN[queue.tail = queue.head];

};

NextAction: ENTRY PROC [handle: SlackHandle] RETURNS [mouseEventProc: MouseEventProc, eventProc: EventProc, inputAction: LIST OF REF ANY, point: Point, clientData: REF ANY] = {

queue: Queue ← handle.queue;

success: BOOL ← TRUE;

errorMsg: Rope.ROPE;

skipActions: NAT;

qeGen: QueueEntryGenerator;

qeGen ← PrepareGenerator[handle];

skipActions ← handle.optimizeProc[qeGen, qeGen.actionsInQueue

! Problem => {success ← FALSE; errorMsg ← msg; CONTINUE}];

IF NOT success THEN RETURN WITH ERROR Problem[msg: errorMsg];

[mouseEventProc, eventProc, inputAction, point, clientData] ← DeQueueAction[handle, skipActions];

IF inputAction = NIL THEN {

handle.slackProcess ← NIL; -- no mouse action. Let process die. Caller will terminate.

};

BROADCAST queue.notFull;

};

QueueSize: INTERNAL PROC [queue: Queue] RETURNS [count: NAT] = {

count ← (queue.tail - queue.head + queue.size) MOD queue.size;

};

PrepareSummary: INTERNAL PROC [handle: SlackHandle] = {

Take all of the events on the queue, in order, and place them on the QueueSummary, starting at location 0.

queueCount: NAT ← QueueSize[handle];

sizeQueue: NAT ← handle.queue.size;

head: NAT ← handle.queue.head;

index: NAT;

FOR i: NAT IN [0..queueCount) DO

index ← (head + i) MOD sizeQueue;

handle.summary.clientDatas[i] ← handle.queue.clientDatas[index];

handle.summary.optimizeHints[i] ← handle.queue.optimizeHints[index];

handle.summary.actions[i] ← handle.queue.actions[index];

handle.summary.points[i] ← handle.queue.points[index];

ENDLOOP;

handle.summary.count ← queueCount;

};

PrepareGenerator: INTERNAL PROC [handle: SlackHandle] RETURNS [qeGen: QueueEntryGenerator] = {

qeGen ← handle.qeGen;

qeGen.queue ← handle.queue;

qeGen.actionsInQueue ← QueueSize[handle.queue]

};

GetQueueEntry: PUBLIC PROC [qeGen: QueueEntryGenerator, index: NAT] RETURNS [clientData: REF ANY, optimizeHint: REF ANY, action: LIST OF REF ANY, point: Point] = {

queue: Queue ← qeGen.queue;

head: NAT ← queue.head;

realIndex: NAT;

IF index + 1 > qeGen.actionsInQueue THEN ERROR Problem[msg: "GetQueueEntry called with index too high"];

realIndex ← (head + index) MOD queue.size;

clientData ← queue.clientDatas[realIndex];

optimizeHint ← queue.optimizeHints[realIndex];

action ← queue.actions[realIndex];

point ← queue.points[realIndex];

};

DeQueueAction: INTERNAL PROC [handle: SlackHandle, skipActions: NAT] RETURNS [mouseEventProc: MouseEventProc, eventProc: EventProc, inputAction: LIST OF REF ANY, point: Point, clientData: REF ANY] = {

queue: Queue ← handle.queue;

queueSize, where: NAT;

queueSize ← QueueSize[handle.queue];

IF skipActions > queueSize THEN ERROR;

IF skipActions = queueSize THEN RETURN[NIL, NIL, NIL, [0,0], NIL]; -- there is nothing left to do

queue.head ← (queue.head + skipActions) MOD queue.size;

where ← queue.head;

mouseEventProc ← queue.mouseProcs[where];

eventProc ← queue.eventProcs[where];

inputAction ← queue.actions[where];

point ← queue.points[where];

clientData ← queue.clientDatas[where];

queue.head ← (queue.head + 1) MOD queue.size;

LogActed[handle.log, inputAction, point, mouseEventProc#NIL, clientData];

};

SlackProcess keeps a ring buffer of recent input actions (called the log) for debugging purposes.

LogRawMouse: PUBLIC ENTRY PROC [handle: SlackHandle, point: Point] = {

ENABLE UNWIND => NULL;

log: Log ← handle.log;

where: NAT ← log.head;

log.events[where] ← $RawMouse;

log.points[where] ← point;

log.head ← (log.head + 1) MOD log.size;

};

LogReceived: INTERNAL PROC [log: Log, event: REF ANY, point: Point, bash: BOOL] = {

where: NAT ← log.head;

log.received[where] ← TRUE;

log.bashed[where] ← bash;

log.events[where] ← event;

log.points[where] ← point;

log.head ← (log.head + 1) MOD log.size;

};

LogActed: INTERNAL PROC [log: Log, action: LIST OF REF ANY, point: Point, mouseEvent: BOOL, clientData: REF ANY] = {

where: NAT ← log.head;

log.received[where] ← FALSE;

log.bashed[where] ← FALSE;

log.events[where] ← action.first;

log.points[where] ← point;

log.head ← (log.head + 1) MOD log.size;

IF log.loggerEnabled THEN log.logger[point, action, mouseEvent, clientData];

};

debugLog: BOOL ← FALSE;

OutputLog: PUBLIC ENTRY PROC [handle: SlackHandle, stream: IO.STREAM] = {

ENABLE UNWIND => NULL;

log: Log ← handle.log;

i: NAT ← (log.head - 1 + log.size) MOD log.size; -- back up pointer one slot

Output the "LogSize-1" most recent events to the stream. The most recent event is output first.

IF debugLog THEN stream.PutF["\nLog Head = %g", IO.int[log.head] ];

stream.PutF["\nMost Recent Event: "];

WHILE i#log.head DO

IF log.events[i] = $RawMouse THEN

stream.PutF["\nRAW MOUSE [%g, %g]",

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE IF log.bashed[i] THEN

IF ISTYPE[log.events[i], ATOM] THEN

stream.PutF["\nBashed %g at [%g, %g]",

[rope[Atom.GetPName[NARROW[log.events[i]]]]],

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE stream.PutF["\nBashed %g at [%g, %g]",

[character[NARROW[log.events[i], REF CHAR]^]],

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE IF log.received[i] THEN

IF ISTYPE[log.events[i], ATOM] THEN

stream.PutF["\nReceived %g at [%g, %g]",

[rope[Atom.GetPName[NARROW[log.events[i]]]]],

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE stream.PutF["\nReceived %g at [%g, %g]",

[character[NARROW[log.events[i], REF CHAR]^]],

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE

IF ISTYPE[log.events[i], ATOM] THEN

stream.PutF["\nActed on %g at [%g, %g]",

[rope[Atom.GetPName[NARROW[log.events[i]]]]],

[real[log.points[i].x]],

[real[log.points[i].y]] ]

ELSE stream.PutF["\nActed on %g at [%g, %g]",

[character[NARROW[log.events[i], REF CHAR]^]],

[real[log.points[i].x]],

[real[log.points[i].y]] ];

i ← (i - 1 + log.size) MOD log.size;

ENDLOOP;

stream.PutF["\nLeast Recent Event.\n"];

};

SlackProcess supports reporting of all actions dequeued from the slack queue, which can be recorded and played back by the client to recreate the session. The client must provide a logging procedure to be called whenever an action is dequeued for the application. The registered LoggingProc will be called at every dequeue of an event.

Creating Session Logs

EnableSessionLogging: PUBLIC ENTRY PROC [handle: SlackHandle] RETURNS [alreadyEnabled: BOOL ← FALSE] = {

ENABLE UNWIND => NULL;

IF handle.log.loggerEnabled THEN alreadyEnabled ← TRUE;

handle.log.loggerEnabled ← TRUE;

};

DisableSessionLogging: PUBLIC ENTRY PROC [handle: SlackHandle] RETURNS [alreadyDisabled: BOOL ← FALSE] = {

ENABLE UNWIND => NULL;

IF NOT handle.log.loggerEnabled THEN alreadyDisabled ← TRUE;

handle.log.loggerEnabled ← FALSE;

};

RegisterLogger: PUBLIC ENTRY PROC [handle: SlackHandle, loggingProc: LoggingProc] RETURNS [alreadyRegistered: BOOL ← FALSE] = {

If you didn't register a loggingProc when you called Create, this gives you another chance.

ENABLE UNWIND => NULL;

IF handle.log.logger#NIL THEN alreadyRegistered ← TRUE;

handle.log.logger ← loggingProc;

};

The registered abortProc will be called (if aborts are enabled) with abortData as argument when the slack process is aborted.

EnableAborts: PUBLIC ENTRY PROC [handle: SlackHandle] RETURNS [alreadyEnabled: BOOL ← FALSE] = {

ENABLE UNWIND => NULL;

IF handle.abort.enabled THEN alreadyEnabled ← TRUE;

handle.abort.enabled ← TRUE;

};

DisableAborts: PUBLIC ENTRY PROC [handle: SlackHandle] RETURNS [alreadyDisabled: BOOL ← FALSE] = {

ENABLE UNWIND => NULL;

IF NOT handle.abort.enabled THEN alreadyDisabled ← TRUE;

handle.abort.enabled ← FALSE;

};

RegisterAbortProc: PUBLIC ENTRY PROC [handle: SlackHandle, abortProc: AbortProc ← NIL, abortData: REF ANY ← NIL, abortViewer: ViewerClasses.Viewer ← NIL] RETURNS [alreadyRegistered: BOOL ← FALSE] = {

The registered abortProc will be called (if aborts are enabled) with abortData as argument when the slack process is aborted. If you didn't register an abortProc when you called Create, this gives you another chance.

ENABLE UNWIND => NULL;

IF handle.abort.proc#NIL THEN alreadyRegistered ← TRUE;

handle.abort.proc ← abortProc;

handle.abort.data ← abortData;

handle.abort.viewer ← abortViewer;

};

END.