\begin{appendix}

\chapter{Schnittstelle {\sl Volatile}}
\label{volatile-ti-sect}

\begin{xple}
\kw{interface} Persistent

\kw{export}

  nilError :\kw{Exception}
  (* Raised if an attempt is made to execute the 'get' function of the
     persistent 'nil' value. *) 
   
  error :\kw{Exception}
  (* Raised if an attempt is made to access a destroyed pesistent.T. *)

  \kw{Let} T(E $<$:\kw{Ok}) = \kw{Tuple} get():E \kw{end}
  (* A persistent value of type 'persistent.T(E)' encapsulates a volatile 
     object of type 'E' that is not stored within the Tycoon persistent object 
     store (for example a window or a file handle). The 'get' function
     retrieves the encapsulated value. Creation, destruction and
     state changes of the encapsulated value are recorded in a persistent log.
     This log is used to propagate commit, savepoint and rollback 
     operations on the Tycoon store to all volatile objects of type 
     'persistent.T(X)'. As a consequence, application programmers can
     treat Tycoon store objects and persistent.T values uniformly.
     Note that A$<$:B implies persistent.T(A) $<$:persistent.T(B). 
     \#\# should become  T(E $<$:+ \kw{Ok}) $<$: Tuple get():E end in future
     versions of the type system :-) *)
     
  \kw{Let} Any = T(\kw{Ok})
  (* The supertype of all persistent.T values. *)
     
  nil :T(Nok)
  (* A polymorphic nil value. 'nil.get()' raises 'nilError'. *)

(* -- Operation Logging: *)

  create(E $<$:\kw{Ok}  create():E  destroy(:E):\kw{Ok}
    indepDestroy :\kw{Bool}  parent :Any  references :\kw{Array}(Any)) :T(E)
  (* Create and register a new persistent.T value by calling 'create' and 
     inserting it into the operation log. The volatile value is assumed to be
     destroyed automatically ('indepDestroy == false') if 'parent' is destroyed
     (either explicitly or via a cascaded 'destroy'). If 'indepDestroy==true',
     a 'destroy' on the parent volatile triggers a call to 'destroy' of this
     persistent.T. If 'create' refers to other volatiles, these have to
     be passed as 'references'. During restart, these referenced
     volatiles are recreated, even if they are only temporary objects. 
     Raise 'error' if 'create' returns a value that is not of type
     'word.T'. *)

  log(V $<$:\kw{Ok}  redo() :V  undo() :\kw{Ok}  parent :Any  references :\kw{Array}(Any)) :V
  (* Log a side effecting operation on a persistent.T value. 
     Execute 'redo' and return its result. For the meaning of 'parent' and
     'references' see the explanation of the 'create' function. *)

  destroy(E $<$:\kw{Ok}  p :T(E)) :\kw{Ok}
  (* Destroy 'p'. Further access to 'p' is not allowed. *)

  enableLogging() :\kw{Ok}
  disableLogging() :\kw{Ok}
  restoreLogging() :\kw{Ok}
  (* Switch operation logging on/off or restore it to its prior state. If
     switched off, operations on persistent.T values are not logged, but 
     creation is still logged. For 'restoreLogging' to work properly, 
     every enable/disable must be followed by a matching 'restoreLogging'. 
     Logging is initially switched on. *)

  loggingEnabled() :\kw{Bool}
  (* Return true if logging is enabled. *)

  unlogged(execute() :\kw{Ok}) :\kw{Ok}
  (* Convenience function: execute 'execute' bracketed by 
     'disable/restoreLogging' *)

(* -- State Restauration: *)

  RestoreProc $<$:\kw{Ok}
  (* The type of handles for restore procedures. *)

  registerRestore(restore():\kw{Ok}  execNow :\kw{Bool}  parent :Any) :RestoreProc
  (* Register a restore procedure that is executed after a rollback or a
     restart to restore the state of volatile objects which is not
     covered by 'create' and 'log' operations. A restore procedure may only
     only reference Tycoon store variables and must not reference
     non-local persistent.T values. The restore procedure is
     deregistered automatically if 'parent' is destroyed. *)
     
  deregisterRestore(restore :RestoreProc) :\kw{Ok}
  (* Deregister a restore procedure. *)

(* -- Callbacks for the Module 'Transaction': *)

  doSavepoint() :\kw{Ok}
  (* Called before next savepoint is established. Append a savepoint entry
     to the operation log. *)

  doCommit() :\kw{Ok}
  (* Called before next commit is performed. Purge the operation log and 
     append a commit entry. *)

  doRollbackTo(syncPoint :\kw{Int}) :\kw{Ok}
  (* Called before module 'transaction' initiates rollback to the given sync
     point (either savepoint or commit point). The sync point is given as an
     integer, where '0' represents a commit point and >0 represents 
     savepoints in chronological order of establishment. After a store
     rollback, 'doRollbackTo' has to be followed by a 'doRestart(true)'. *)

  doRestart(afterRollback :\kw{Bool}) :\kw{Ok}
  (* Re-execute the opeation log starting from the beginning and walk
     down restore list (if 'afterRollback==true', just walks down
     restore list) *) 

end;
\end{xple}

\chapter{Schnittstelle {\sl Transaction}}
\label{transaction-ti-sec}

\begin{xple}
\kw{interface} Transaction

\kw{export}

  Via $<$:\kw{Ok}

  Savepoint $<$: \kw{Ok}

  error :\kw{Exception}
  (* Raised when commit or savepoint fails. *)

  commitVia, rollbackVia, restartVia :Via

  savepoint() :\kw{Tuple} s :Savepoint v :Via \kw{end}

  commit() :Via

  rollbackTo(s :Savepoint) :\kw{Ok}

  rollbackToLast() :\kw{Ok}

  rollback() :\kw{Ok}

\kw{end};
\end{xple}
\end{appendix}
