Invocation (affect.Affect.Action.Private.Action.Invocation)

Invocations

type 'a action := 'a t

type 'a t

The type for action invocations.

val make : 
  ?unblock:'a primitive ->
  'a action ->
  (exn * Stdlib.Printexc.raw_backtrace, 'a t) Stdlib.Either.t

make action is an invocation for action it is:

Right invocation, if everything went well.
Left (exn, bt) if one of the action's Action.guards raised. For now we advise to throw it into the continuation of Invoke or Invoke_poll.

unblock if provided is added as a choice to action but is not reported in the meta of the resulting invocation. That all it does. For the rest it just behaves as if you had given Action.choose [unblock; action].

val meta : 'a t -> Meta.t

meta invocation is the metadata derived from the action given at make.

Synchronizing

val do_poll : 
  continue:('a Result.t -> unit -> unit) ->
  'a t ->
  (unit -> unit) option

do_poll ~continue invocation must be called on an Invoke or Invoke_poll effect with continue a function that invokes the effect's continuation. The result is:

Some k, if the synchronization of action succeeds without blocking. k is continue partially applied with the invocation's result. It can be directly invoked or scheduled as being ready for execution.
None if the synchronization of action would block. In this case continue is left untouched. If you are handling Invoke_poll you should continue with None and if you are handling Invoke you should move on to call do_block

val do_block : unblock:('a Result.t -> unit) -> 'a t -> unit

do_block ~unblock invocation must be called on an Invoke after – and only after – a call to do_poll on invocation returned None.

unblock r is called with the invocation result r when invocation eventually synchronizes. This call should just schedule the continuation of Invoke with r in your scheduler It must not directly invoke it.

The call to unblock may happen during the do_block call already, or only later, or never. Given the latter it may also never be gc'd or only much later so so think carefully about what you hold on to in the closure. Another dimension is that it may end up being called in an arbitrary context so if you lookup domain local storage prepare for it being absent or present but not the one you expect!