package eio

You can search for identifiers within the package.

in-package search v0.2.0

On This Page

Cancellation

package eio

eio
- Eio
  - Buf_read
    
    Syntax
  - Buf_write
    
    BE
    
    LE
  - Cancel
  - Condition
  - Debug
  - Domain_manager
    
    t
  - Exn
  - Fiber
    
    List
  - File
    
    ro
    
    rw
  - Flow
    
    close
    
    sink
    
    source
    
    two_way
  - Fs
    
    Unix_perm
    
    dir
    
    dir_with_close
  - Generic
    
    t
  - Mutex
  - Net
    
    Ipaddr
    
    V4
    
    V6
    
    Sockaddr
    
    datagram_socket
    
    listening_socket
    
    socket
    
    stream_socket
    
    t
  - Path
  - Private
    
    Ctf
    
    Control
    
    Debug
    
    Effects
    
    Fiber_context
    
    Suspend
    
    Waiters
  - Promise
  - Semaphore
  - Std
  - Stdenv
  - Stream
  - Switch
  - Time
    
    Timeout
    
    clock
eio.mock
- Eio_mock
  - Action
  - Backend
  - Clock
  - Flow
  - Handler
  - Net
eio.unix
- Eio_unix
  - Ctf
  - FD
  - Ipaddr
  - Private
eio.utils
- Eio_utils
  - Lf_queue
  - Suspended
  - Zzz
    
    Key

Legend:
Library
Module
Module type
Parameter
Class
Class type

Every fiber has an associated context.

type t

val make_root : unit -> t

Make a new root context for a new domain.

val destroy : t -> unit

destroy t removes t from its cancellation context.

val tid : t -> Ctf.id

Cancellation

The Cancel module describes the user's view of cancellation.

Internally, when the user calls a primitive operation that needs to block the fiber, the Suspend callback effect is performed. This suspends the fiber and calls callback from the scheduler's context, passing it the suspended fiber's context. If the operation can be cancelled, the callback should use set_cancel_fn to register a cancellation function.

There are two possible outcomes for the operation: it may complete normally, or it may be cancelled. If it is cancelled then the registered cancellation function is called. This function will always be called from the fiber's own domain, but care must be taken if the operation is being completed by another domain at the same time.

Consider the case of Stream.take, which can be fulfilled by a Stream.add from another domain. We want to ensure that either the item is removed from the stream and returned to the waiting fiber, or that the operation is cancelled and the item is not removed from the stream.

Therefore, cancelling and completing both attempt to clear the cancel function atomically, so that only one can succeed. The case where Stream.take succeeds before cancellation:

A fiber calls Suspend and is suspended. The callback sets a cancel function and registers a waiter on the stream.
When another domain has an item, it removes the cancel function (making the take uncancellable) and begins resuming the fiber with the new item.
If the taking fiber is cancelled after this, the cancellation will be ignored and the operation will complete successfully. Future operations will fail immediately, however.

The case of cancellation winning the race:

A fiber calls Suspend and is suspended. The callback sets a cancel function and registers a waiter on the stream.
The taking fiber is cancelled. Its cancellation function is called, which starts removing the waiter.
If another domain tries to provide an item to the waiter as this is happening, it will try to clear the cancel function and fail. The item will be given to the next waiter instead.

Note that there is a mutex around the list of waiters, so the taking domain can't finish removing the waiter and start another operation while the adding domain is trying to resume it. In future, we may want to make this lock-free by using a fresh atomic to hold the cancel function for each operation.

Note: A fiber will only have a cancel function set while it is suspended.

val cancellation_context : t -> Cancel.t

cancellation_context t is t's current cancellation context.

val set_cancel_fn : t -> (exn -> unit) -> unit

set_cancel_fn t fn sets fn as the fiber's cancel function.

If the cancellation context is cancelled, the function is removed and called. When the operation completes, you must call clear_cancel_fn to remove it.

val clear_cancel_fn : t -> bool

clear_cancel_fn t removes the function previously set with set_cancel_fn, if any.

Returns true if this call removed the function, or false if there wasn't one. This operation is atomic and thread-safe. An operation that completes in another domain must use this to indicate that the operation is finished (can no longer be cancelled) before enqueuing the result. If it returns false, the operation was cancelled first and the canceller has called (or is calling) the function. If it returns true, the caller is responsible for any resources owned by the function, such as the continuation.

val get_error : t -> exn option

get_error t is Cancel.get_error (cancellation_context t)