[gnugo-devel] API functions and the role of the Position struct.

[Gunnar Farneback]

I'm about to implement the first two parts of TODO item * (was it
really a good idea to remove the numbering of the TODO items?):

| * a) Add move history for "permanent" moves (i.e. ones done with
|   play_move(), in contrast to temporary moves done by
|   trymove()/tryko()) in the board code. Notice that the move history
|   must be added to the state in the Position struct.
|
|   b) Implement undo for "permanent" moves in the board code and
|   replace various other undo implementations in play_gtp.c,
|   play_ascii.c, and play_gmp.c with this.

This will have some repercussions on the Position struct and it's use
in the gnugo_* API functions. For the context of the discussion below,
assume that the board state will become more complex than currently
and that a proper undo for permanent moves will become available.

---

The gnugo_* API functions in engine/interface.c have the common format

void gnugo_xxxx(Position *pos, ...)

where pos is a struct holding the board state, and gnugo_xxxx()
performs some action on the state. This approach has a number of
consequences:

1. Since the engine is implemented as something working on an internal
   state stored in global variables, it's necessary to copy the state
   on entrance and exit. Generally the body of a gnugo_*() function
   looks like

   position_to_globals(pos);
   [...]
   globals_to_position(pos);

2. Code using the API functions can modify the board state by writing
   directly into the position struct.

3. Code using the API functions can switch between several different
   board positions by having multiple position structs around.


In my opinion this leads to some problems.

i.   The use of external state in the API doesn't fit very well with
     the internal state in the engine and has in fact caused a couple
     of bugs over the years.

ii.  The copying of state in (1) above is meaningless in most
     practical situations and a potential performance problem for
     certain applications.

iii. The possibility to modify the state externally as described in
     (2) is a real problem, should anyone make use of it. Currently it
     would probably work, but it would break when the state becomes
     more complex. Code using the API should only be able to modify
     the board state through functions like gnugo_play_move() and (a
     future) gnugo_undo_move().

iv.  Switching between different board positions leads to bad use of
     various caches within the engine and should not be encouraged.
     When undo becomes available, this feature also shouldn't be very
     important.


What I want to do can in short be described as changing the API to
work with an internal state instead of an external state, taking out
the position struct from the API functions. This would generally
simplify the code and make the API conceptually more similar to the
GTP interface. Read access to the board state would be provided by
accessor functions (gnugo_get_board() and similar) instead of
inspection of the position struct. If needed, the possibility to work
with multiple board positions can still be provided by store_board()
and restore_board() type functions.

Opinions?

/Gunnar