std.net.socket.UnixSocket

class pub UnixSocket

A low-level, non-blocking Unix domain socket.

Static methods

new

Show source code

fn pub static new(type: Type) -> Result[UnixSocket, Error] {
  let sock = RawSocket(
    inner: 0 as Int32,
    registered: 0 as UInt8,
    unix: 1 as UInt8,
  )

  match inko_socket_new(UNIX, type.into_int, mut sock) as Int {
    case 0 -> Result.Ok(UnixSocket(raw: sock, deadline: NO_DEADLINE))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub static new(type: Type) -> Result[UnixSocket, Error]

Creates a new Unix domain socket.

Examples

Creating a new socket:

import std.net.socket (Type, UnixSocket)

UnixSocket.new(Type.DGRAM).get

Instance methods

accept

Show source code

fn pub accept -> Result[UnixSocket, Error] {
  let sock = RawSocket(
    inner: 0 as Int32,
    registered: 0 as UInt8,
    unix: 1 as UInt8,
  )

  match
    inko_socket_accept(_INKO.state, _INKO.process, @raw, @deadline, mut sock)
      as Int
  {
    case 0 -> Result.Ok(UnixSocket(raw: sock, deadline: NO_DEADLINE))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub accept -> Result[UnixSocket, Error]

Accepts a new incoming connection from this socket.

This method will not return until a connection is available.

Examples

Accepting a connection and reading data from the connection:

import std.net.socket (Type, UnixSocket)

let listener = UnixSocket.new(Type.STREAM).get
let stream = UnixSocket.new(Type.STREAM).get

listener.bind('/tmp/test.sock'.to_path).get
listener.listen.get

stream.connect('/tmp/test.sock').get
stream.write_string('ping').get

let client = listener.accept.get
let buffer = ByteArray.new

client.read(into: buffer, size: 4).get

buffer.to_string # => 'ping'

bind

Show source code

fn pub mut bind(path: ref Path) -> Result[Nil, Error] {
  match inko_socket_bind(@raw, path.to_string, 0) {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut bind(path: ref Path) -> Result[Nil, Error]

Binds this socket to the specified path or abstract address.

Examples

Binding a Unix socket to a path:

import std.net.socket (Type, UnixSocket)

let socket = UnixSocket.new(Type.DGRAM).get

socket.bind('/tmp/test.sock'.to_path).get

connect

Show source code

fn pub mut connect(path: ref Path) -> Result[Nil, Error] {
  match
    inko_socket_connect(
      _INKO.state,
      _INKO.process,
      @raw,
      path.to_string,
      0,
      @deadline,
    )
  {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut connect(path: ref Path) -> Result[Nil, Error]

Connects this socket to the specified address.

Examples

Connecting a Unix socket:

import std.net.socket (Type, UnixSocket)

let listener = UnixSocket.new(Type.STREAM).get
let stream = UnixSocket.new(Type.STREAM).get

listener.bind('/tmp/test.sock'.to_path).get
listener.listen.get

stream.connect('/tmp/test.sock').get

flush

Show source code

fn pub mut flush -> Result[Nil, Never] {
  Result.Ok(nil)
}

fn pub mut flush -> Result[Nil, Never]

Flushes any pending writes.

listen

Show source code

fn pub mut listen -> Result[Nil, Error] {
  match inko_socket_listen(@raw, MAXIMUM_LISTEN_BACKLOG) {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut listen -> Result[Nil, Error]

Marks this socket as being ready to accept incoming connections using accept().

Examples

Marking a socket as a listener:

import std.net.socket (Type, UnixSocket)

let socket = UnixSocket.new(Type.STREAM).get

socket.bind('/tmp/test.sock'.to_path).get
socket.listen.get

local_address

Show source code

fn pub local_address -> Result[UnixAddress, Error] {
  let raw = RawAddress(address: '', port: 0)

  match inko_socket_local_address(_INKO.state, @raw, mut raw) as Int {
    case 0 -> Result.Ok(UnixAddress.new(raw.address.to_path))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub local_address -> Result[UnixAddress, Error]

Returns the local address of this socket.

peer_address

Show source code

fn pub peer_address -> Result[UnixAddress, Error] {
  let raw = RawAddress(address: '', port: 0)

  match inko_socket_peer_address(_INKO.state, @raw, mut raw) as Int {
    case 0 -> Result.Ok(UnixAddress.new(raw.address.to_path))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub peer_address -> Result[UnixAddress, Error]

Returns the peer address of this socket.

print

Show source code

fn pub mut print(string: String) -> Result[Nil, Error] {
  write_string(string).then(fn (_) { write_string('\n') })
}

fn pub mut print(string: String) -> Result[Nil, Error]

Writes the entirety of string to the underlying stream, followed by writing a Unix newline to the stream.

read

Show source code

fn pub mut read(into: mut ByteArray, size: Int) -> Result[Int, Error] {
  match
    inko_socket_read(_INKO.state, _INKO.process, @raw, into, size, @deadline)
  {
    case { @tag = 0, @value = v } -> Result.Ok(v)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut read(into: mut ByteArray, size: Int) -> Result[Int, Error]

Reads bytes from a stream into a ByteArray.

The return value is the number of bytes read.

The size argument specifies how many bytes are to be read. The actual number of bytes read may be less than this value.

read_all

Show source code

fn pub mut read_all(bytes: mut ByteArray) -> Result[Int, Error] {
  let mut total = 0
  let mut read_size = INITIAL_READ_ALL_SIZE

  loop {
    let bytes_read = try read(into: bytes, size: read_size)

    if bytes_read == 0 { return Result.Ok(total) }

    total += bytes_read

    # To reduce the overhead of large buffer reads, we increase the buffer
    # size as more data is read.
    if read_size < MAX_READ_ALL_SIZE { read_size *= 2 }
  }
}

fn pub mut read_all(bytes: mut ByteArray) -> Result[Int, Error]

Reads all bytes from the stream into the ByteArray.

If an error is encountered while reading, this method stops reading any more bytes and re-throws the error.

The return value is the number of bytes read.

receive_buffer_size=

Show source code

fn pub mut receive_buffer_size=(value: Int) -> Result[Nil, Error] {
  set_option(const.SOL_SOCKET, const.SO_RCVBUF, value.to_int)
}

fn pub mut receive_buffer_size=(value: Int) -> Result[Nil, Error]

Sets the value of the SO_RCVBUF option.

receive_from

Show source code

fn pub mut receive_from(
  bytes: mut ByteArray,
  size: Int,
) -> Result[UnixAddress, Error] {
  let raw = RawAddress(address: '', port: 0)

  match
    inko_socket_receive_from(
      _INKO.state,
      _INKO.process,
      @raw,
      bytes,
      size,
      @deadline,
      mut raw,
    )
      as Int
  {
    case 0 -> Result.Ok(UnixAddress.new(raw.address.to_path))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut receive_from(bytes: mut ByteArray, size: Int) -> Result[UnixAddress, Error]

Receives a single datagram message on the socket, returning the address the message was sent from.

The message is read into the given ByteArray, and up to size bytes will be read.

Examples

Sending a message to ourselves and receiving it:

import std.net.socket (Type, UnixSocket)

let socket = UnixSocket.new(Type.DGRAM).get
let bytes = ByteArray.new

socket.send_string_to('hello', address: '/tmp/test.sock'.to_path).get

let received_from = socket.receive_from(bytes: bytes, size: 5).get

bytes.to_string         # => 'hello'
received_from.to_string # => '/tmp/test.sock'

reset_deadline

Show source code

fn pub mut reset_deadline {
  @deadline = NO_DEADLINE
}

fn pub mut reset_deadline

Clears the deadline to apply to socket operations.

send_buffer_size=

Show source code

fn pub mut send_buffer_size=(value: Int) -> Result[Nil, Error] {
  set_option(const.SOL_SOCKET, const.SO_SNDBUF, value.to_int)
}

fn pub mut send_buffer_size=(value: Int) -> Result[Nil, Error]

Sets the value of the SO_SNDBUF option.

send_bytes_to

Show source code

fn pub mut send_bytes_to(
  bytes: ref ByteArray,
  address: ref Path,
) -> Result[Int, Error] {
  let addr = address.to_string

  match
    inko_socket_send_bytes_to(
      _INKO.state,
      _INKO.process,
      @raw,
      bytes,
      addr,
      0,
      @deadline,
    )
  {
    case { @tag = 0, @value = v } -> Result.Ok(v)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut send_bytes_to(bytes: ref ByteArray, address: ref Path) -> Result[Int, Error]

Sends a ByteArray to the given address.

The return value is the number of bytes sent.

Examples

import std.net.socket (Type, UnixSocket)

let socket = UnixSocket.new(Type.DGRAM).get
let bytes = 'hello'.to_byte_array

socket.bind('/tmp/test.sock'.to_path).get
socket
  .send_bytes_to(bytes: bytes, address: '/tmp/test.sock'.to_path)
  .get

send_string_to

Show source code

fn pub mut send_string_to(
  string: String,
  address: ref Path,
) -> Result[Int, Error] {
  let addr = address.to_string

  match
    inko_socket_send_string_to(
      _INKO.state,
      _INKO.process,
      @raw,
      string,
      addr,
      0,
      @deadline,
    )
  {
    case { @tag = 0, @value = v } -> Result.Ok(v)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut send_string_to(string: String, address: ref Path) -> Result[Int, Error]

Sends a String to the given address.

The return value is the number of bytes sent.

Examples

import std.net.socket (Type, UnixSocket)

let socket = UnixSocket.new(Type.DGRAM).get

socket.bind('/tmp/test.sock'.to_path).get
socket
  .send_string_to(string: 'hello', address: '/tmp/test.sock'.to_path)
  .get

shutdown

Show source code

fn pub mut shutdown -> Result[Nil, Error] {
  match inko_socket_shutdown_read_write(@raw) {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut shutdown -> Result[Nil, Error]

Shuts down both the reading and writing half of this socket.

shutdown_read

Show source code

fn pub mut shutdown_read -> Result[Nil, Error] {
  match inko_socket_shutdown_read(@raw) {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut shutdown_read -> Result[Nil, Error]

Shuts down the reading half of this socket.

shutdown_write

Show source code

fn pub mut shutdown_write -> Result[Nil, Error] {
  match inko_socket_shutdown_write(@raw) {
    case { @tag = 1, @value = _ } -> Result.Ok(nil)
    case { @tag = _, @value = e } -> Result.Error(Error.from_os_error(e))
  }
}

fn pub mut shutdown_write -> Result[Nil, Error]

Shuts down the writing half of this socket.

timeout_after=

Show source code

fn pub mut timeout_after=[T: ToInstant](deadline: ref T) {
  @deadline = deadline.to_instant.to_int
}

fn pub mut timeout_after=[T: ToInstant](deadline: ref T)

Sets the point in time after which socket operations must time out, known as a "deadline".

Examples

Using a Duration results in this method calculating the absolute time after which operations time out:

import std.net.socket (UnixSocket, Type)
import std.time (Duration)

let socket = UnixSocket.new(Type.DGRAM)

socket.timeout_after = Duration.from_secs(5)

We can also use an Instant:

import std.net.socket (UnixSocket, Type)
import std.time (Duration, Instant)

let socket = UnixSocket.new(Type.DGRAM)

socket.timeout_after = Instant.new + Duration.from_secs(5)

try_clone

Show source code

fn pub try_clone -> Result[UnixSocket, Error] {
  let sock = RawSocket(
    inner: 0 as Int32,
    registered: 0 as UInt8,
    unix: 1 as UInt8,
  )

  match inko_socket_try_clone(@raw, mut sock) as Int {
    case 0 -> Result.Ok(UnixSocket(raw: sock, deadline: NO_DEADLINE))
    case e -> Result.Error(Error.from_os_error(e))
  }
}

fn pub try_clone -> Result[UnixSocket, Error]

Attempts to clone the socket.

Cloning a socket may fail, such as when the program has too many open file descriptors.

write_bytes

Show source code

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error] {
  write_all_internal(bytes.to_pointer, bytes.size)
}

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error]

Writes the entirety of bytes to the underlying stream.

Types implementing this method must guarantee that upon returning from this method, either all of the data is written and a Ok(Nil) is returned, or an Error(Error) is returned.

write_string

Show source code

fn pub mut write_string(string: String) -> Result[Nil, Error] {
  write_all_internal(string.to_pointer, string.size)
}

fn pub mut write_string(string: String) -> Result[Nil, Error]

Writes the entirety of string to the underlying stream.

See Write.write_bytes for more details.

Implemented traits

std.drop.

Drop

impl Drop for UnixSocket

std.io.

Read

impl Read for UnixSocket

std.io.

Write

impl Write for UnixSocket