let pub @socket: UnixSocket

The raw UnixSocket wrapped by this UnixClient.

fn pub static new(address: ref Path) -> Result[UnixClient, Error] {
  let socket = try UnixSocket.stream

  try socket.connect(address)
  Result.Ok(UnixClient(socket))
}

fn pub static new(address: ref Path) -> Result[UnixClient, Error]

Creates a new UnixClient that is connected to the given address.

This method doesn't enforce a deadline on establishing the connection. If you need to limit the amount of time spent waiting to establish the connection, use UnixClient.with_timeout instead.

Examples

Connecting a UnixClient:

import std.net.socket (UnixServer, UnixClient)

let listener = UnixServer.new('/tmp/test.sock'.to_path).get

UnixClient.new('/tmp/test.sock'.to_path).get

fn pub static with_timeout[T: ToInstant](
  address: ref Path,
  timeout_after: ref T,
) -> Result[UnixClient, Error] {
  let socket = try UnixSocket.stream

  socket.timeout_after = timeout_after
  try socket.connect(address)
  socket.reset_deadline
  Result.Ok(UnixClient(socket))
}

fn pub static with_timeout[T: ToInstant](address: ref Path, timeout_after: ref T) -> Result[UnixClient, Error]

Creates a new UnixClient but limits the amount of time spent waiting for the connection to be established.

The timeout_after argument specifies the deadline after which the connect() times out. The deadline is cleared once connected.

See UnixClient.new for more information.

Examples

import std.net.socket (UnixClient)
import std.time (Duration)

UnixClient
  .with_timeout(
    address: '/tmp/test.sock'
    timeout_after: Duration.from_secs(5)
  )
  .get

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

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

Flushes any pending writes to the file system.

Flushing writes is a potentially expensive operation, and unnecessarily calling this method may degrade performance.

When flushing data to disk it's important to remember that the actual behaviour may vary based on the type of file system, operating system and storage hardware that's used. In particular, it's possible for one of these components to say "Yup, I totally flushed the data, you're all good!" when in fact they have not fully flushed the data.

fn pub local_address -> Result[UnixAddress, Error] {
  @socket.local_address
}

fn pub local_address -> Result[UnixAddress, Error]

Returns the local address of this socket.

See the documentation of UnixSocket.local_address for more information.

fn pub peer_address -> Result[UnixAddress, Error] {
  @socket.peer_address
}

fn pub peer_address -> Result[UnixAddress, Error]

Returns the peer address of this socket.

See the documentation of UnixSocket.peer_address for more information.

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.

fn pub mut read(into: mut ByteArray, size: Int) -> Result[Int, Error] {
  @socket.read(into, size)
}

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

Reads up to size bytes from self into the given ByteArray, returning the number of bytes read.

The into argument is the ByteArray to read the bytes into. The capacity of this ByteArray is increased automatically if necessary.

The size argument specifies how many bytes are to be read.

The return value is the number of bytes read.

The number of bytes read may be less than size. This can happen for different reasons, such as when all input is consumed or not enough data is available (yet).

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

  loop {
    match read(into: bytes, size: read_size) {
      case Ok(0) -> return Result.Ok(total)
      case Ok(n) -> {
        total += n

        # To reduce the number of calls to `Reader.read` when there's lots of
        # input to consume, we increase the read size if deemed beneficial.
        if read_size < MAX_READ_ALL_SIZE and n == read_size { read_size *= 2 }
      }
      case Error(e) -> throw e
    }
  }
}

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

Reads from self into the given ByteArray, returning when all input is consumed.

The return value is the number of bytes read.

Errors

This method returns an Error if the underlying call to Read.read returns an Error.

fn pub mut read_exact(into: mut ByteArray, size: Int) -> Result[Nil, Error] {
  let mut pending = size

  while pending > 0 {
    match read(into, pending) {
      case Ok(0) if pending > 0 -> throw Error.EndOfInput
      case Ok(n) -> pending -= n
      case Error(e) -> throw e
    }
  }

  Result.Ok(nil)
}

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

Reads exactly size bytes into into.

Whereas Read.read might return early if fewer bytes are available in the input stream, Read.read_exact continues reading until the desired amount of bytes is read.

Errors

If the end of the input stream is encountered before filling the buffer, an Error.EndOfInput error is returned.

If an error is returned, no assumption can be made about the state of the into buffer, i.e. there's no guarantee data read so far is in the buffer in the event of an error.

fn pub mut shutdown -> Result[Nil, Error] {
  @socket.shutdown
}

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

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

fn pub mut shutdown_read -> Result[Nil, Error] {
  @socket.shutdown_read
}

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

Shuts down the reading half of this socket.

fn pub mut shutdown_write -> Result[Nil, Error] {
  @socket.shutdown_write
}

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

Shuts down the writing half of this socket.

fn pub try_clone -> Result[UnixClient, Error] {
  @socket.try_clone.map(fn (sock) { UnixClient(sock) })
}

fn pub try_clone -> Result[UnixClient, Error]

Attempts to clone the socket.

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

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

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.

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

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.