Module Eio_net_chaos.FaultSource

The faults a wrapper injects.

type t =
  1. | Short of int
    (*

    A read or a write moves at most max 1 n bytes. A write cut short found the socket's buffer full, so the next write on that end waits, as on eio_posix, and other fibers run meanwhile.

    *)
  2. | Stall of float
    (*

    The operation waits that many seconds of the clock, then runs.

    *)
  3. | Hang
    (*

    On a connection, a read or a write that meets it silences the connection for good, as when the peer's host loses power or a partition cuts the path, and on AF_UNIX as when the peer's process hangs: from then on nothing crosses it either way, and no close or reset comes. Each end reads what is queued to it on a Unix-domain connection, as AF_UNIX queues at the reader what a returned write sent (unix(7)), and nothing more over IP, not even an end of stream already sent, then waits. Its writes fill its buffer, then wait. Neither end's shutdown or close reaches the other. A wait ends with a cancel or the end's own shutdown: a read then returns end of file, and a write raises Connection_reset. Of later faults on the connection, only Short and Stall act. Over TCP the end's kernel also gives up, with ETIMEDOUT: after its keepalive probes, or once a byte it sent goes unacknowledged for TCP_USER_TIMEOUT, or for 948.6 s on Linux and 18 s on macOS (Eio_net_mem.v). An end with no keepalive and nothing unacknowledged waits for ever, so a program with no timeout of its own hangs. run silences a connection at a read. On a network other than Eio_net_mem, where the wrapper does not see the peer, only this end's reads go silent.

    On a connect, an accept or a receive, the operation waits until a cancel ends it; a connect never does in run, as the kernel gives up on it. It holds that one operation: a datagram taken by a receive that hangs goes to the next receive, and a connection taken by an accept that hangs to the next accept. A receive on a Unix-domain datagram socket does not hang: the datagram it took was queued when its send returned.

    *)
  4. | Reset
    (*

    Over IP, the connection is reset at both ends, and the bytes not yet read are lost. At each end the first read or write that follows raises Connection_reset; later reads return end of file and writes keep raising it, as on Linux and macOS. A Unix-domain connection has no reset to send: it is the crash of one end, the peer on a read and this end on a write, which closes its socket. AF_UNIX keeps in the reader's queue what a returned write sent, so each end reads that first. The other end then reads Connection_reset once, if the crashed end left bytes unread, as AF_UNIX reports it, then end of file; the crashed end reads end of file. The crashed end's code still runs, so it still reads what was queued to it: a program may hold that what its peer's returned writes sent arrives. The writes of both raise Connection_reset, as AF_UNIX's EPIPE, which leaves the reset to the reads. On a network other than Eio_net_mem, each end of a Unix-domain connection reads what is queued, then Connection_reset once. On an accept, the accept succeeds and the connection it returns is reset, as Linux hands over one whose client left first. On a connect, it is a refusal, as a reset answering the handshake is.

    *)
  5. | Eof
    (*

    One end closes, as a FIN does: no byte already written is lost. On a read, the peer closed: the read returns what the peer wrote before, then end of file. On a write, this end closed: the write raises Connection_reset, and the peer reads the bytes written before, then end of file. On an accept, the client closed. After it, the end that closed reads end of file and its writes raise Connection_reset; the other end's first write goes through, its bytes lost, and the next ones raise Connection_reset, as on Linux after the peer closes. On a Unix-domain connection each of its writes raises it, as AF_UNIX raises EPIPE, and the end that closed reads what is queued to it first.

    *)
  6. | Refuse
    (*

    A connect fails with Connection_failure (Refused _).

    *)
  7. | Timeout
    (*

    A connect fails after 133 seconds of the clock, 75 under `Macos or 21 under `Windows, as a lost handshake does, with the error eio_posix raises then: Eio.Io (Eio.Exn.X (Eio_unix.Unix_error (ETIMEDOUT, "connect-in-progress", "")), _). Eio does not classify it as a Connection_failure.

    *)
  8. | Unreachable
    (*

    A connect fails at once, as one with no route to its host does, with the error eio_posix raises then: Eio.Io (Eio.Exn.X (Eio_unix.Unix_error (ENETUNREACH, "connect", "")), _).

    *)
  9. | No_descriptor
    (*

    An accept fails with the error eio_posix raises when the process has no descriptor left: Eio.Io (Eio.Exn.X (Eio_unix.Unix_error (EMFILE, "accept", "")), _), which Eio_net.Accept.classify reads as `Descriptors. As on Linux, the connection stays queued and its client sees nothing, and every accept on the network fails the same way until the program frees a descriptor, by closing a connection, socket or listener of the network, or by ending the switch that holds one. The next accept then returns that connection, with its data. run does not try it, as Eio.Net.run_server stops on it.

    *)
  10. | Drop
    (*

    The datagram is lost; the receive waits for the next one.

    *)
  11. | Dup
    (*

    The datagram arrives now and again on the next receive.

    *)
  12. | Reorder
    (*

    The datagram arrives after the next one.

    *)
  13. | Garble of int
    (*

    n bytes of noise arrive in place of the datagram, from the same sender.

    *)

The type for faults. One that does not apply to an operation does nothing, such as one that AF_UNIX cannot produce on a Unix-domain socket: Timeout and Unreachable on a connect, and Drop, Dup, Reorder, Garble and Hang on a datagram. Reset on the accept of a Unix-domain connection is a client that closed, as Eof.

val pp : t Fmt.t

pp formats a fault for logs and reports.