Skip to content

lori

actor ClientTCPConnection

ClientTCPConnection¶

A client TCP connection actor driven by a ClientTCPConnectionNotify.

Wraps lori's TCPConnection class and ClientLifecycleEventReceiver trait into a single actor, forwarding lifecycle callbacks to the notifier you provide. This is the notifier-based alternative to implementing TCPConnectionActor and ClientLifecycleEventReceiver yourself.

Sending data¶

write and writev are fire-and-forget behaviors: they call send() on the underlying connection and discard the result. A send that cannot be accepted (connection not open, backpressure) is silently dropped — no callback fires for it. An accepted send produces on_send_accepted, then exactly one of on_sent or on_send_failed on the notifier.

Synchronous methods¶

Callbacks receive conn: ClientTCPConnection ref. Synchronous methods on the actor — buffer_until, socket options, close, set_timer, etc. — are callable from any callback and take effect immediately.

actor tag ClientTCPConnection is
  TCPConnectionActor[RuntimeBackend ref] tag,
  ClientLifecycleEventReceiver[RuntimeBackend ref] ref

Implements¶

TCPConnectionActor[RuntimeBackend ref] tag
ClientLifecycleEventReceiver[RuntimeBackend ref] ref

Constructors¶

create¶

Open a plaintext client connection to host:service.

new tag create(
  auth: TCPConnectAuth val,
  notify: ClientTCPConnectionNotify iso,
  host: String val,
  service: String val,
  from: String val = "",
  read_buffer_size: ReadBufferSize = call,
  ip_version: IPVersion = .,
  connection_timeout: (ConnectionTimeout | None val) = reference)
: ClientTCPConnection tag^

Parameters¶

auth: TCPConnectAuth val
notify: ClientTCPConnectionNotify iso
host: String val
service: String val
from: String val = ""
read_buffer_size: ReadBufferSize = call
ip_version: IPVersion = .
connection_timeout: (ConnectionTimeout | None val) = reference

Returns¶

ClientTCPConnection tag^

ssl¶

Open an SSL client connection to host:service. The SSL session is created from ctx. on_connected fires after the TLS handshake completes.

new tag ssl(
  auth: TCPConnectAuth val,
  notify: ClientTCPConnectionNotify iso,
  ctx: SSLContext val,
  host: String val,
  service: String val,
  from: String val = "",
  read_buffer_size: ReadBufferSize = call,
  ip_version: IPVersion = .,
  connection_timeout: (ConnectionTimeout | None val) = reference)
: ClientTCPConnection tag^

Parameters¶

auth: TCPConnectAuth val
notify: ClientTCPConnectionNotify iso
ctx: SSLContext val
host: String val
service: String val
from: String val = ""
read_buffer_size: ReadBufferSize = call
ip_version: IPVersion = .
connection_timeout: (ConnectionTimeout | None val) = reference

Returns¶

ClientTCPConnection tag^

Public Behaviours¶

write¶

Send data on this connection. Fire-and-forget: the send is silently dropped if the connection is not open or is under backpressure. An accepted send produces on_send_accepted, then on_sent or on_send_failed on the notifier.

be write(
  data: ByteSeq)

Parameters¶

data: ByteSeq

writev¶

Send multiple buffers in a single syscall. Same fire-and-forget semantics as write.

be writev(
  data: ByteSeqIter val)

Parameters¶

data: ByteSeqIter val

mute¶

Stop reading from the socket until unmute is called. Takes effect on the next turn, not immediately — use YieldReading from on_received for an immediate one-shot pause.

be mute()

unmute¶

Resume reading after a mute.

be unmute()

dispose¶

be dispose()

Public Functions¶

buffer_until¶

Set the number of bytes to buffer before delivering data via on_received. Pass Streaming to deliver all available data as it arrives.

fun ref buffer_until(
  qty: (BufferSize | Streaming val))
: BufferUntilResult

Parameters¶

qty: (BufferSize | Streaming val)

Returns¶

BufferUntilResult

close¶

Gracefully close the connection. Sends already accepted by the underlying connection are delivered before close completes. Because close is synchronous and write is a behavior, a write call in the same callback runs after close — use write before close, not after.

fun ref close()
: None val

Returns¶

None val

hard_close¶

Close the connection immediately, dropping any queued data.

fun ref hard_close()
: None val

Returns¶

None val

start_tls¶

Initiate a TLS handshake on an established plaintext connection. Returns None when the handshake starts, or a StartTLSError if the upgrade cannot proceed. On success, on_tls_ready fires. On failure, on_tls_failure fires followed by on_closed.

fun ref start_tls(
  ssl_ctx: SSLContext val,
  host: String val = "")
: (None val | StartTLSError)

Parameters¶

ssl_ctx: SSLContext val
host: String val = ""

Returns¶

(None val | StartTLSError)

set_nodelay¶

Turn Nagle on/off. Returns 0 on success, or a non-zero errno on failure.

fun box set_nodelay(
  state: Bool val)
: U32 val

Parameters¶

state: Bool val

Returns¶

U32 val

keepalive¶

Set the TCP keepalive timeout. Pass 0 to disable.

fun ref keepalive(
  secs: U32 val)
: None val

Parameters¶

secs: U32 val

Returns¶

None val

local_address¶

Return the local IP address.

fun ref local_address()
: NetAddress val

Returns¶

NetAddress val

remote_address¶

Return the remote IP address.

fun ref remote_address()
: NetAddress val

Returns¶

NetAddress val

idle_timeout¶

Set or disable the idle timeout. The timer fires when no data is sent or received for the configured duration. Pass None to disable.

fun ref idle_timeout(
  duration: (IdleTimeout | None val))
: None val

Parameters¶

duration: (IdleTimeout | None val)

Returns¶

None val

set_timer¶

Create a one-shot timer. Returns a TimerToken on success. Only one timer can be active at a time; cancel the existing one first.

fun ref set_timer(
  duration: TimerDuration)
: (TimerToken val | SetTimerError)

Parameters¶

duration: TimerDuration

Returns¶

(TimerToken val | SetTimerError)

cancel_timer¶

Cancel an active timer. Safe to call with stale tokens.

fun ref cancel_timer(
  token: TimerToken val)
: None val

Parameters¶

token: TimerToken val

Returns¶

None val

set_read_buffer_minimum¶

Set the shrink-back floor for the read buffer.

fun ref set_read_buffer_minimum(
  new_min: ReadBufferSize)
: (ReadBufferResized val | ReadBufferResizeBelowBufferSize val)

Parameters¶

new_min: ReadBufferSize

Returns¶

(ReadBufferResized val | ReadBufferResizeBelowBufferSize val)

resize_read_buffer¶

Force the read buffer to a specific size.

fun ref resize_read_buffer(
  size': ReadBufferSize)
: ReadBufferResizeResult

Parameters¶

size': ReadBufferSize

Returns¶

ReadBufferResizeResult

get_so_rcvbuf¶

Get the OS receive buffer size. Returns (errno, value).

fun box get_so_rcvbuf()
: (U32 val , U32 val)

Returns¶

(U32 val , U32 val)

set_so_rcvbuf¶

Set the OS receive buffer size. Returns 0 on success, or errno.

fun box set_so_rcvbuf(
  bufsize: U32 val)
: U32 val

Parameters¶

bufsize: U32 val

Returns¶

U32 val

get_so_sndbuf¶

Get the OS send buffer size. Returns (errno, value).

fun box get_so_sndbuf()
: (U32 val , U32 val)

Returns¶

(U32 val , U32 val)

set_so_sndbuf¶

Set the OS send buffer size. Returns 0 on success, or errno.

fun box set_so_sndbuf(
  bufsize: U32 val)
: U32 val

Parameters¶

bufsize: U32 val

Returns¶

U32 val

getsockopt_u32¶

Get a socket option as a U32. Returns (errno, value).

fun box getsockopt_u32(
  level: I32 val,
  option_name: I32 val)
: (U32 val , U32 val)

Parameters¶

level: I32 val
option_name: I32 val

Returns¶

(U32 val , U32 val)

setsockopt_u32¶

Set a socket option as a U32. Returns 0 on success, or errno.

fun box setsockopt_u32(
  level: I32 val,
  option_name: I32 val,
  option: U32 val)
: U32 val

Parameters¶

level: I32 val
option_name: I32 val
option: U32 val

Returns¶

U32 val

is_closed¶

True when the connection is closed or closing.

fun box is_closed()
: Bool val

Returns¶

Bool val

is_writeable¶

True when the socket can currently send.

fun box is_writeable()
: Bool val

Returns¶

Bool val