Search results

There are no results.

std.net.socket.TcpClient

class pub TcpClient

A TCP socket connected to another TCP socket.

Fields

socket

let pub @socket: Socket

The raw Socket wrapped by this TcpClient.

Static methods

new

Show source code
Hide source code
fn pub static new(ip: ref IpAddress, port: Int) -> Result[TcpClient, Error] {
  let socket = try Socket.stream(ip.v6?)

  try socket.connect(ip, port)
  from(socket)
}
fn pub static new(ip: ref IpAddress, port: Int) -> Result[TcpClient, Error]

Creates a new TcpClient that is connected to the TCP socket at the given IP address and port.

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 TcpClient.with_timeout instead.

Examples

Connecting a TcpClient:

import std.net.socket (TcpClient)
import std.net.ip (IpAddress)

TcpClient.new(IpAddress.v4(127, 0, 0, 1), port: 40_000).get

with_timeout

Show source code
Hide source code
fn pub static with_timeout[T: ToInstant](
  ip: ref IpAddress,
  port: Int,
  timeout_after: ref T,
) -> Result[TcpClient, Error] {
  let socket = try Socket.stream(ip.v6?)

  socket.timeout_after = timeout_after
  try socket.connect(ip, port)
  socket.reset_deadline
  from(socket)
}
fn pub static with_timeout[T: ToInstant](ip: ref IpAddress, port: Int, timeout_after: ref T) -> Result[TcpClient, Error]

Creates a new TcpClient 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 TcpClient.new for more information.

Examples

import std.net.socket (TcpClient)
import std.net.ip (IpAddress)
import std.time (Duration)

TcpClient
  .with_timeout(
    ip: IpAddress.v4(0, 0, 0, 0),
    port: 40_000,
    timeout_after: Duration.from_secs(5)
  )
  .get

Instance methods

flush

Show source code
Hide source code
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.

local_address

Show source code
Hide source code
fn pub local_address -> Result[SocketAddress, Error] {
  @socket.local_address
}
fn pub local_address -> Result[SocketAddress, Error]

Returns the local address of this socket.

See the documentation of Socket.local_address for more information.

peer_address

Show source code
Hide source code
fn pub peer_address -> Result[SocketAddress, Error] {
  @socket.peer_address
}
fn pub peer_address -> Result[SocketAddress, Error]

Returns the peer address of this socket.

See the documentation of Socket.peer_address for more information.

print

Show source code
Hide 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
Hide source code
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).

read_all

Show source code
Hide 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 {
    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.

read_exact

Show source code
Hide source code
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.

shutdown

Show source code
Hide source code
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.

shutdown_read

Show source code
Hide source code
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.

shutdown_write

Show source code
Hide source code
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.

try_clone

Show source code
Hide source code
fn pub try_clone -> Result[TcpClient, Error] {
  @socket.try_clone.map(fn (sock) { TcpClient(sock) })
}
fn pub try_clone -> Result[TcpClient, 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
Hide source code
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.

write_string

Show source code
Hide source code
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.

Implemented traits

std.io.

Read

impl Read for TcpClient
std.io.

Write

impl Write for TcpClient