The AutoRepeat interface provides support for calling a procedure repetitively. Auto-repeating typically takes place while a key or mouse button is held down, although there is no direct relation between AutoRepeat and VBTs.

When an auto-repeat object ar is activated, it forks a {\it timer thread\/} that calls ar.repeat() after firstWait milliseconds, and every period milliseconds thereafter. However, there is a flow-control mechanism: if the call to ar.repeat() has not returned by the time the next repetition is scheduled to take place, the timer thread will wait. That is, repetitions cannot queue up more than one deep.

An auto-repeat object ar is activated by a call to Start(ar), terminated by a call to Stop(ar), and resumed by a call to Continue(ar).

All locking is handled within AutoRepeat; calls to Start(ar), Stop(ar), and Continue(ar) are serialized on a per-ar basis. These procedures may be called by a repeat method. Clients must not call the repeat method directly; it is called by the timer thread subject to client-calls to Start, Stop, and Continue. The AutoRepeat interface will never call a repeat method re-entrantly.

INTERFACE AutoRepeat;

TYPE
  Milliseconds = CARDINAL;

CONST
  DefaultFirstWait: Milliseconds = 500;
  DefaultPeriod   : Milliseconds = 66;

TYPE
  T <: Public;
  Public =
    Private OBJECT
    METHODS
      init (firstWait: Milliseconds := DefaultFirstWait;
            period   : Milliseconds := DefaultPeriod): T;
      repeat ();
      canRepeat(): BOOLEAN;
    END;
  Private <: ROOT;

The call ar.canRepeat should return FALSE whenever there's reason to suspect that a client might want to call Stop in the near future. The next call to ar.repeat will be suspended for period milliseconds. The default for this method always returns TRUE.

The canRepeat method is intended for situations when a repeat method takes more time than period milliseconds to complete. The problem with slow repeat methods is that the scheduler might decide to always run the timer thread (since it will want to call the repeat method as soon as the slow repeat method completes), thereby blocking another thread from being able to call Stop.

The default repeat method is a no-op.

PROCEDURE Start (ar: T);

Initiate auto-repeating for ar.

PROCEDURE Stop (ar: T);

Stop auto-repeating as soon as possible.

It is possible (but unlikely) that ar.repeat() is called one more time after a call to Stop(ar) returns. This can happen because calls to ar.repeat are not serialized with respect to the call to Stop(ar). They are not serialized in order to allow a repeat method to call Stop.

PROCEDURE Continue (ar: T);

Resume auto-repeating immediately.

END AutoRepeat.