eio 0.7 · OCaml Package

Networking.

Example:

let addr = `Tcp (Ipaddr.V4.loopback, 8080)

let http_get ~net ~stdout addr =
  Switch.run @@ fun sw ->
  let flow = Net.connect ~sw net addr in
  Flow.copy_string "GET / HTTP/1.0\r\n\r\n" flow;
  Flow.shutdown flow `Send;
  Flow.copy flow stdout

type connection_failure =

| Refused of Exn.Backend.t
| No_matching_addresses
| Timeout

type error =

| Connection_reset of Exn.Backend.t
(*
This is a wrapper for epipe, econnreset and similar errors. It indicates that the flow has failed, and data may have been lost.
*)
| Connection_failure of connection_failure

type Exn.err +=

| E of error

val err : error -> exn

err e is Eio.Exn.create (Net e)

module Ipaddr : sig ... end

IP addresses.

module Sockaddr : sig ... end

Network addresses.

Provider Interfaces

class virtual socket : object ... end

class virtual stream_socket : object ... end

class virtual datagram_socket : object ... end

class virtual listening_socket : object ... end

class virtual t : object ... end

Out-bound Connections

val connect : 
  sw:Switch.t ->
  t ->
  Sockaddr.stream ->
  < stream_socket
  ; Flow.close >

connect ~sw t addr is a new socket connected to remote address addr.

The new socket will be closed when sw finishes, unless closed manually first.

val with_tcp_connect : 
  ?timeout:Time.Timeout.t ->
  host:string ->
  service:string ->
  t ->
  (< stream_socket ; Flow.close > -> 'b) ->
  'b

with_tcp_connect ~host ~service t f creates a tcp connection conn to host and service and executes f conn.

conn is closed after f returns (if it isn't already closed by then).

host is either an IP address or a domain name, eg. "www.example.org", "www.ocaml.org" or "127.0.0.1".

service is an IANA recognized service name or port number, eg. "http", "ftp", "8080" etc. See https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml.

Addresses are tried in the order they are returned by getaddrinfo, until one succeeds.

parameter timeout
Limits how long to wait for each connection attempt before moving on to the next. By default there is no timeout (beyond what the underlying network does).

raises Connection_failure
A connection couldn't be established for any of the addresses defined for host.

Incoming Connections

val listen : 
  ?reuse_addr:bool ->
  ?reuse_port:bool ->
  backlog:int ->
  sw:Switch.t ->
  t ->
  Sockaddr.stream ->
  listening_socket

listen ~sw ~backlog t addr is a new listening socket bound to local address addr.

The new socket will be closed when sw finishes, unless closed manually first.

For (non-abstract) Unix domain sockets, the path will be removed afterwards.

parameter backlog
The number of pending connections that can be queued up (see listen(2)).

parameter reuse_addr
Set the Unix.socket_bool_option.SO_REUSEADDR socket option. For Unix paths, also remove any stale left-over socket.

parameter reuse_port
Set the Unix.socket_bool_option.SO_REUSEPORT socket option.

val accept : 
  sw:Switch.t ->
  listening_socket ->
  < stream_socket ; Flow.close > * Sockaddr.stream

accept ~sw socket waits until a new connection is ready on socket and returns it.

The new socket will be closed automatically when sw finishes, if not closed earlier. If you want to handle multiple connections, consider using accept_fork instead.

val accept_fork : 
  sw:Switch.t ->
  listening_socket ->
  on_error:(exn -> unit) ->
  (stream_socket -> Sockaddr.stream -> unit) ->
  unit

accept_fork socket fn accepts a connection and handles it in a new fiber.

After accepting a connection to socket, it runs fn flow client_addr in a new fiber.

flow will be closed when fn returns.

val accept_sub : 
  sw:Switch.t ->
  listening_socket ->
  on_error:(exn -> unit) ->
  (sw:Switch.t -> stream_socket -> Sockaddr.stream -> unit) ->
  unit

deprecated Use accept_fork instead

Datagram Sockets

val datagram_socket : 
  ?reuse_addr:bool ->
  ?reuse_port:bool ->
  sw:Switch.t ->
  t ->
  [< Sockaddr.datagram | `UdpV4 | `UdpV6 ] ->
  < datagram_socket
  ; Flow.close >

datagram_socket ~sw t addr creates a new datagram socket bound to addr. The new socket will be closed when sw finishes.

`UdpV4 and `UdpV6 represents IPv4 and IPv6 datagram client sockets where the OS assigns the next available socket address and port automatically. `Udp .. can be used to create both listening server socket and client socket.

parameter reuse_addr
Set the Unix.socket_bool_option.SO_REUSEADDR socket option.

parameter reuse_port
Set the Unix.socket_bool_option.SO_REUSEPORT socket option.

val send : datagram_socket -> Sockaddr.datagram -> Cstruct.t -> unit

send sock addr buf sends the data in buf to the address addr using the the datagram socket sock.

val recv : datagram_socket -> Cstruct.t -> Sockaddr.datagram * int

recv sock buf receives data from the socket sock putting it in buf. The number of bytes received is returned along with the sender address and port. If the buf is too small then excess bytes may be discarded depending on the type of the socket the message is received from.

DNS queries

val getaddrinfo : ?service:string -> t -> string -> Sockaddr.t list

getaddrinfo ?service t node returns a list of IP addresses for node. node is either a domain name or an IP address.

parameter service
is a human friendly textual name for internet services assigned by IANA., eg. 'http', 'https', 'ftp', etc.
For a more thorough treatment, see getaddrinfo.

val getaddrinfo_stream : ?service:string -> t -> string -> Sockaddr.stream list

getaddrinfo_stream is like getaddrinfo, but filters out non-stream protocols.

val getaddrinfo_datagram : 
  ?service:string ->
  t ->
  string ->
  Sockaddr.datagram list

getaddrinfo_datagram is like getaddrinfo, but filters out non-datagram protocols.

val getnameinfo : t -> Sockaddr.t -> string * string

getnameinfo t sockaddr is (hostname, service) corresponding to sockaddr. hostname is the registered domain name represented by sockaddr. service is the IANA specified textual name of the port specified in sockaddr, e.g. 'ftp', 'http', 'https', etc.

val close : < close : unit.. > -> unit

Closing

close t marks the socket as closed. It can no longer be used after this.

package eio

Provider Interfaces

Out-bound Connections

Incoming Connections

Datagram Sockets

DNS queries