Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
ChessClocks

NAME

ChessClocks - general interface for chess clocks

SYNOPSIS

TYPE ChessClock = POINTER TO ChessClockRec;
TYPE ChessClockRec = RECORD (Services.ObjectRec) END;
TYPE Player = SHORTINT; (* player number, starting from 0 *)



TYPE StartProc = PROCEDURE (chessclock: ChessClock;
                            auth: Shards.Lid) : BOOLEAN;
TYPE StopProc = PROCEDURE (chessclock: ChessClock;
                           auth: Shards.Lid) : BOOLEAN;
TYPE SwitchProc = PROCEDURE (chessclock: ChessClock;
                             auth: Shards.Lid; player: Player) : BOOLEAN;
TYPE RunningProc = PROCEDURE (chessclock: ChessClock) : BOOLEAN;
TYPE CurrentPlayerProc = PROCEDURE (chessclock: ChessClock) : Player;
TYPE GetClockProc = PROCEDURE (chessclock: ChessClock; player: Player;
                               VAR clock: Clocks.Clock);
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
      RECORD
         (Objects.ObjectRec)
         start: StartProc;
         stop: StopProc;
         switch: SwitchProc;
         running: RunningProc;
         currentPlayer: CurrentPlayerProc;
         getClock: GetClockProc;
      END;



PROCEDURE Init(chessclock: ChessClock; if: Interface;
               numberOfPlayers: SHORTINT;
               timelimit: Times.Time);



PROCEDURE Start(chessclock: ChessClock; auth: Shards.Lid) : BOOLEAN;
PROCEDURE Stop(chessclock: ChessClock; auth: Shards.Lid) : BOOLEAN;
PROCEDURE Switch(chessclock: ChessClock;
                 auth: Shards.Lid; player: Player) : BOOLEAN;



PROCEDURE Running(chessclock: ChessClock) : BOOLEAN;
PROCEDURE CurrentPlayer(chessclock: ChessClock) : Player;
PROCEDURE GetClock(chessclock: ChessClock; player: Player;
                   VAR clock: Clocks.Clock);



PROCEDURE NumberOfPlayers(chessclock: ChessClock) : SHORTINT;
PROCEDURE GetTimeLimit(chessclock: ChessClock;
                       VAR timelimit: Times.Time);
PROCEDURE TimeLeft(chessclock: ChessClock; player: Player;
                   VAR time: Times.Time);

DESCRIPTION

A chess clock is a set of n clocks representing the total times of n players playing a turn-based game. Initially, all clocks are set to 0. As long the game is neither terminated nor suspended, exactly one clock is running, representing the player whose turn it is. The chess clock has to be switched as soon as it is the next players turn. All players share a common time limit. As soon as the time limit expires for one of the players, the chess clock can no longer be switched to him. The remaining players can continue the game until one player is left.

Those operations that suspend, restart, or switch the chess clock require an authorization. All other retrieval operations can be freely invoked. This allows a game manager to keep control over the chess clock while permitting read-only access to all players.

Players and their corresponding clocks are enumerated from 0 to n-1. At maximum 128 players are supported. The number of the current player is returned by CurrentPlayer. Note however, that this value is -1 as long as Switch has not been called yet or if the chess clock is suspended. The number of players n is returned by NumberOfPlayers.

Start starts a newly created or suspended chess clock. Stop suspends the chess clock until Start is invoked again. Both operations may return FALSE in case of authorization failures. Running returns TRUE if the chess clock is running. Switch sets the current player to player. If the chess clock is running, this causes the clock of the previous player to stop and the clock of player to continue. If the chess clock has not started yet or is suspended, then the clock of player will be started as soon as the chess clock resumes. Note that Switch should be invoked before Start is called for the first time to indicate the beginning player. Otherwise, the first turn is implicitly assigned to player 0.

GetClock returns the individual clock of the given player. TimeLeft returns the time left for that player. GetTimeLimit returns the total time which was assigned initially to each of the players.

Implementation interface

Init associates chessclock with the given interface for the given number of players and fixed time limit which is to be given as relative time measure. All interface procedures must be non-NIL and are expected to meet following specification:

start: PROCEDURE(chessclock: ChessClock; auth: Shards.Lid) : BOOLEAN;: Start or resume the chess clock. Assume an implicit switch to player 0 if no player has been active yet. FALSE is to be returned in case of failures.
stop: PROCEDURE(chessclock: ChessClock; auth: Shards.Lid) : BOOLEAN;: Suspend the chess clock, i.e. stop the currently running clock. FALSE is to be returned in case of failures.
switch: PROCEDURE(chessclock: ChessClock; auth: Shards.Lid; player: Player) : BOOLEAN;: Define player to be the current player.
running: PROCEDURE(chessclock: ChessClock) : BOOLEAN;: Return TRUE if the chess clock is currently running.
currentPlayer: PROCEDURE(chessclock: ChessClock) : Player;: Return -1 if the chess clock is not running. Otherwise the player whose clock is currently running, is to be returned.
getClock: PROCEDURE(chessclock: ChessClock; player: Player; VAR clock: Clocks.Clock);: Return the clock of the given player.

DIAGNOSTICS

ChessClocks does not generate any error events.