# module Crystal::EventLoop::Socket

##
Overview

The socket module is empty by default and filled with abstract defs when crystal/system/socket.cr is required.

##
Direct including types

- Crystal::EventLoop

##
Defined in:

crystal/event_loop.cr
crystal/event_loop/socket.cr

##
Instance Method Summary

- #accept(socket : ::Socket) : Tuple(::Socket::Handle, Bool) | Nil

  Accepts an incoming TCP connection on the socket.

- #close(socket : ::Socket) : Nil

  Closes the system socket fd or handle.

- #connect(socket : ::Socket, address : ::Socket::Addrinfo | ::Socket::Address, timeout : Time::Span | Nil) : IO::Error | Nil

  Opens a connection on socket to the target address.

- #read(socket : ::Socket, slice : Bytes) : Int32

  Reads at least one byte from the socket into slice.

- #receive_from(socket : ::Socket, slice : Bytes) : Tuple(Int32, ::Socket::Address)

  Receives at least one byte from the socket into slice, capturing the source address.

- #send_to(socket : ::Socket, slice : Bytes, address : ::Socket::Address) : Int32

  Sends at least one byte from slice to the socket with a target address address.

- #shutdown(socket : ::Socket) : Nil

  Internal shutdown of the socket.

- #socket(family : ::Socket::Family, type : ::Socket::Type, protocol : ::Socket::Protocol, blocking : Bool | Nil) : Tuple(::Socket::Handle, Bool)

  Creates a new socket file descriptor or handle and returns it, along with whether the blocking flag has been set.

- #socketpair(type : ::Socket::Type, protocol : ::Socket::Protocol) : Tuple(Tuple(::Socket::Handle, ::Socket::Handle), Bool)

  Creates a pair of UNIX socket file descriptors or handles and returns them, along with whether the blocking mode has been set.

- #wait_readable(socket : ::Socket) : Nil

  Blocks the current fiber until the socket is ready for read.

- #wait_writable(socket : ::Socket) : Nil

  Blocks the current fiber until the socket is ready for write.

- #write(socket : ::Socket, slice : Bytes) : Int32

  Writes at least one byte from slice to the socket.

##
Instance Method Detail

abstract def accept(socket : ::Socket) : Tuple(::Socket::Handle, Bool) | Nil #

Accepts an incoming TCP connection on the socket.

Blocks the current fiber if no connection is waiting, continuing when one becomes available. Otherwise returns immediately.

Returns a handle to the socket for the new connection.

abstract def close(socket : ::Socket) : Nil #

Closes the system socket fd or handle.

abstract def connect(socket : ::Socket, address : ::Socket::Addrinfo | ::Socket::Address, timeout : Time::Span | Nil) : IO::Error | Nil #

Opens a connection on socket to the target address.

Blocks the current fiber and continues when the connection is established.

Returns `IO::Error` in case of an error. The caller is responsible for raising it as an exception if necessary.

abstract def read(socket : ::Socket, slice : Bytes) : Int32 #

Reads at least one byte from the socket into slice.

Blocks the current fiber if no data is available for reading, continuing when available. Otherwise returns immediately.

Returns the number of bytes read (up to `slice.size`). Returns 0 when the socket is closed and no data available.

Use `#receive_from` for capturing the source address of a message.

abstract def receive_from(socket : ::Socket, slice : Bytes) : Tuple(Int32, ::Socket::Address) #

Receives at least one byte from the socket into slice, capturing the source address.

Blocks the current fiber if no data is available for reading, continuing when available. Otherwise returns immediately.

Returns a tuple containing the number of bytes received (up to `slice.size`) and the source address.

abstract def send_to(socket : ::Socket, slice : Bytes, address : ::Socket::Address) : Int32 #

Sends at least one byte from slice to the socket with a target address address.

Blocks the current fiber if the socket is not ready for writing, continuing when ready. Otherwise returns immediately.

Returns the number of bytes sent (up to `slice.size`).

abstract def shutdown(socket : ::Socket) : Nil #

Internal shutdown of the socket. Called after the `Socket` has been marked closed but before calling `#close` to actually close the system socket fd or handle.

Implementations shall resume all pending waiters and let them fail because the IO has been closed. They don't have to call the `#shutdown` syscall.

abstract def socket(family : ::Socket::Family, type : ::Socket::Type, protocol : ::Socket::Protocol, blocking : Bool | Nil) : Tuple(::Socket::Handle, Bool) #

Creates a new socket file descriptor or handle and returns it, along with whether the blocking flag has been set.

abstract def socketpair(type : ::Socket::Type, protocol : ::Socket::Protocol) : Tuple(Tuple(::Socket::Handle, ::Socket::Handle), Bool) #

Creates a pair of UNIX socket file descriptors or handles and returns them, along with whether the blocking mode has been set.

abstract def wait_readable(socket : ::Socket) : Nil #

Blocks the current fiber until the socket is ready for read.

abstract def wait_writable(socket : ::Socket) : Nil #

Blocks the current fiber until the socket is ready for write.

abstract def write(socket : ::Socket, slice : Bytes) : Int32 #

Writes at least one byte from slice to the socket.

Blocks the current fiber if the socket is not ready for writing, continuing when ready. Otherwise returns immediately.

Returns the number of bytes written (up to `slice.size`).

Use `#send_to` for sending a message to a specific target address.