4.3. The notification mechanism

Often, one just wants to watch an engine, and to perform a special action when it reaches a final state. There is a simple way to configure a callback:

  val when_state : ?is_done:('a -> unit) ->
		   ?is_error:(exn -> unit) ->
		   ?is_aborted:(unit -> unit) ->
		   'a #engine ->
		     unit

For example, to output a message when eng1 is connected:

  when_state ~is_done:(fun _ -> prerr_endline "eng1 connected") eng1

The argument of is_done is the result of the engine (not needed in this example).

The function when_state is implemented with the notification mechanism all engines must support. The method request_notification can be used to request a callback whenever the state of the engine changes:

  method request_notification : (unit -> bool) -> unit

The callback function returns whether it is still interested in being called (true) or not (false). In the latter case, the engine must not call the function again.

For example, the connection message can also be output by:

  eng1 # request_notification 
           (fun () -> 
	      match eng1#state with
	        `Done _ -> prerr_endline "eng1 connected"; false
              | `Error _
              | `Aborted -> false
              | `Working _ -> true
           )

Some more details: The callback function must be even called when only minor state changes occur, e.g. when `Working n changes to `Working (n+1). The engine is free to invoke the callback function even more frequently.

Another detail: It is allowed that more callbacks are requested when a callback function is running.

Note that all engine construction classes base on the notification mechanism, so it is absolutely required that it is implemented error-free.