SlackProcessImpl.mesa
Copyright © 1986 by Xerox Corporation. All rights reserved.
Last edited by Pier on November 5, 1986 7:05:50 pm PST
Bier, November 6, 1986 2:09:48 pm PST
DIRECTORY
Atom, CedarProcess, IO, Process, Rope, SlackProcess, TIPUser, Terminal, 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[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.