class[['a, 'b]]
map_engine :map_done:('a -> 'b engine_state) -> ?map_error:exn -> 'b engine_state -> ?map_aborted:unit -> 'b engine_state -> ?propagate_working:bool -> 'a #engine ->
['b]
engine
map_engine
observes the argument engine, and when the
state changes to `Done
, `Error
, or `Aborted
, the corresponding
mapping function is called, and the resulting state becomes the state
of the mapped engine. If the engine is already in one of the
mentioned states, the map functions are also called (unlike
when_state
).
After the state change to `Done
, `Error
, or `Aborted
has been
observed, the map engine detaches from the argument engine,
and no further state changes are recognized.
The state `Working
cannot be mapped to another state. It is an
error to map final states to `Working
.
The result type of the map_*
functions is engine_state
and not final_state
because of historic reasons.
If the mapped engine is aborted, this request will be forwarded to the argument engine.
If one of the mapping functions raises an exception, this causes
a transiton to `Error
.
map_done
: Maps the `Done
state of the argument engine to
another state. The argument of map_done
is the argument of the
`Done
state. Note that map_done
is non-optional only because
of typing. If it were optional, the type checker would infer 'a = 'b
.map_error
: Maps the `Error
state of the argument engine to
another state. The argument of map_error
is the argument of the
`Error
state.map_aborted
: Maps the `Aborted
state of the argument engine to
another state.propagate_working
: Specifies whether changes of the `Working
state in the argument engine are propagated. Defaults to true
.
If set to false
, the mapped engine remains in `Working 0
until
it transitions to a final state.