12. Beyond SPARK: the server¶
The engine is proved, but it cannot run a game by itself. Something has to
keep time, accept connections, hold each player's latest controls and run
the bots. That is the server, in server/src/. It is ordinary Ada, not
SPARK, and this chapter looks at the Ada features it uses and at where the
proofs stop.
Library first¶
The server is a library with a thin program on top. A match is an object you create and stop, so tests can run many matches, and several servers, in one process:
type Match (Players : Player_Count) is limited private;
type Match_Access is access Match;
-- Starts a match at once. The plan says who is in each seat. With a
-- Record_Path, the match is recorded there (see Recording).
function Create
(Plan : Seat_Plan; Seed : Natural; Record_Path : String := "")
return Match_Access
with Pre => Plan'First = 1 and then Plan'Last in Player_Count;
limited private means the type's contents are hidden from users of the
package, and that it cannot be copied: a running match is one thing, not a
value. access Match is a pointer type. The server allocates matches on the
heap, which the engine never does.
The precondition is still there. Contracts work in ordinary Ada too. They are not proved here, but they are checked at run time, as in the engine's tests.
Protected objects¶
Several things touch a match at once: the clock, each bot, and each HTTP request carrying a player's controls. In Ada, shared data goes in a protected object:
protected type State (Players : Player_Count) is
procedure Start (Seed : Natural);
procedure Set (P : Player_Id; C : Control);
-- Steps the world; Used and At_Tick are the controls applied and
-- the tick they were applied at.
procedure Tick
(Used : out Control_Array; At_Tick : out Adawars.Rules.Tick);
...
private
W : World (Players) := New_World (Players, 0);
Controls : Control_Array (1 .. Players) := [others => Idle];
The data, in the private part, can only be reached through the protected operations. Ada guarantees that procedures run one at a time, with no other operation running, and that functions can run together but never alongside a procedure. No locks are taken by hand, so none can be forgotten.
The tick itself is the engine's Step:
Step's precondition requires a valid world. The server only ever has worlds
that came from New_World and Step, both proved to produce valid worlds.
So the precondition, checked at run time here, never fails.
Tasks¶
The clock is a task: a thread, declared as part of the language.
task body Clock is
Next : Ada.Calendar.Time;
begin
select
accept Start;
or
terminate;
end select;
Next := Ada.Calendar.Clock;
while M.S.Running loop
Next := Next + Tick_Length;
delay until Next;
accept Start waits until another task calls the clock's Start entry: a
rendezvous. The select ... or terminate lets the task end quietly if it is
never started. delay until Next sleeps to an absolute time, so the ticks do
not drift however long each one takes.
Where the proofs stop¶
The server's job is to move data between the outside world and the engine. At both edges, it hands the decision to proved code.
Coming in, a player's controls go through the proved decoder of chapter 11:
function Decode_Control (Raw : String) return Decoded is
-- Renumbered from 1, which also meets Wire.Decode's precondition.
Text : constant String (1 .. Raw'Length) := Raw;
D : constant Adawars.Wire.Decoded := Adawars.Wire.Decode (Text);
Going out, each player gets the proved view of chapter 10, and bots decide from the same view, with no more information than a human has:
What is not proved: that the HTTP code is correct, that the clock keeps time, that the bots fly well. A bug there can make the game unplayable. It cannot break a rule, show a player something they should not see, or decide a match wrongly, because none of those are the server's to decide.
That is the design to take away. Put the decisions in a small core you can prove, make everything else a messenger, and make the messages pass through proved code at both ends.
Recap¶
- Ordinary Ada keeps contracts, checked at run time.
limited privatetypes hide their contents and cannot be copied.- Protected objects make shared data safe without hand-written locks.
- Tasks, entries and
delay untilare part of the language. - Keep the decisions in the proved core, and route the outside world through it.