silk/native_socket

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.

Scoped nonblocking TCP and pathname-Unix connections and listeners over ByteDuplex.

When to use

Use connectResolvedOwned or connectUnixOwned when the caller must retain an outbound connection. The shorter connectResolved and connectUnix operations consume the same owner into a protected callback scope. Use listen or listenUnix for one affine listener, then accept one independently owned Connection at a time.

Details

Every native syscall is nonblocking. Temporary unavailability uses zero-time poll followed by a positive MonotonicClock wait. One acquisition deadline is shared by every sequential candidate or accept retry. Socket flush means kernel acceptance, not delivery to the peer.

Gotchas

Timer polling trades readiness latency for a bounded idle poll rate. A None deadline may wait indefinitely. Listener close never unlinks a pathname. Structured Effect exits close once; fatal traps carry no cleanup guarantee. Darwin setup is single-threaded and does not promise cross-thread fork safety.

Import as NativeSocket with import silk.native_socket { NativeSocket }.

Public declarations: 33.

ConnectionPhase

pub enum ConnectionPhase

The visible directional lifetime of one native connection.

Connecting

Connecting = 0

Native connection establishment has not completed.

Open

Open = 1

The descriptor is available for its permitted operations.

WriteClosed

WriteClosed = 2

The local write direction is closed; reads remain available.

Closed

Closed = 3

The descriptor is terminally closed.

NativeSocketOperation

pub enum NativeSocketOperation

The native boundary that produced a socket failure.

Socket

Socket = 0

Native socket creation.

Configure

Configure = 1

Native descriptor or socket-option setup.

Connect

Connect = 2

Native outbound connection establishment.

Bind

Bind = 3

Native local-address binding.

Listen

Listen = 4

Native listener activation.

GetSocketName

GetSocketName = 5

Native bound-address inspection.

Accept

Accept = 6

Native incoming connection acceptance.

ConvertAddress

ConvertAddress = 7

Conversion of a returned native address.

Poll

Poll = 8

Native zero-time readiness inspection.

GetSocketOption

GetSocketOption = 9

Native socket error inspection.

Read

Read = 10

Native input transfer.

Write

Write = 11

Native output transfer.

ShutdownWrite

ShutdownWrite = 12

Native write-direction shutdown.

Close

Close = 13

Native terminal descriptor release.

ListenerPhase

pub enum ListenerPhase

The visible lifetime of one native listener.

Open

Open = 0

The descriptor is available for its permitted operations.

Closed

Closed = 1

The descriptor is terminally closed.

ListenOptionsReason

pub enum ListenOptionsReason

The rejected ListenOptions field.

KernelBacklog

KernelBacklog = 0

The kernel backlog is outside 1..65535.

PollInterval

PollInterval = 1

The polling interval is outside 1..1,000,000,000 nanoseconds.

ListenOptionsError

pub struct ListenOptionsError

A typed ListenOptions admission failure.

Field reason

pub reason: ListenOptionsReason

The input admission rule that failed.

Field value

pub value: u64

The rejected option value.

InvalidBindReason

pub enum InvalidBindReason

The rejected local pathname condition.

EmptyPath

EmptyPath = 0

The pathname contains no bytes.

RelativePath

RelativePath = 1

The pathname does not start with a slash.

NulPath

NulPath = 2

The pathname contains a NUL byte.

AbstractPath

AbstractPath = 3

The pathname requests an unsupported abstract address.

ConnectOptionsReason

pub enum ConnectOptionsReason

The rejected ConnectOptions field.

PollInterval

PollInterval = 0

The polling interval is outside 1..1,000,000,000 nanoseconds.

MaxAttempts

MaxAttempts = 1

The connection attempt limit is outside 1..1024.

ConnectOptionsError

pub struct ConnectOptionsError

A typed ConnectOptions admission failure.

Field reason

pub reason: ConnectOptionsReason

The input admission rule that failed.

Field value

pub value: u64

The rejected option value.

InvalidEndpointReason

pub enum InvalidEndpointReason

The rejected endpoint or pathname condition.

EmptyEndpoints

EmptyEndpoints = 0

The endpoint list is empty.

TooManyEndpoints

TooManyEndpoints = 1

The endpoint count exceeds the attempt limit.

EmptyPath

EmptyPath = 2

The pathname contains no bytes.

RelativePath

RelativePath = 3

The pathname does not start with a slash.

NulPath

NulPath = 4

The pathname contains a NUL byte.

PathTooLong

PathTooLong = 5

The pathname and its terminator exceed native address capacity.

AbstractPath

AbstractPath = 6

The pathname requests an unsupported abstract address.

AttemptFailure

pub union AttemptFailure

One nonrecursive failure retained when the attempt budget is exhausted.

ConnectionRefused

AttemptFailure.ConnectionRefused: AttemptFailure

The peer refused the connection.

NetworkUnreachable

AttemptFailure.NetworkUnreachable: AttemptFailure

The destination network is unreachable.

AddressUnavailable

AttemptFailure.AddressUnavailable: AttemptFailure

The requested address is unavailable.

NativeFailure

AttemptFailure.NativeFailure { operation: NativeSocketOperation, errno: i32 }: AttemptFailure

A native boundary failed with the retained operation and error number.

Field operation

pub operation: NativeSocketOperation

The native or byte-I/O operation that failed.

Field errno

pub errno: i32

The native error number reported by the selected platform.

NativeSocketError

pub union NativeSocketError

A native socket acquisition or explicit lifecycle failure.

AttemptsExhausted

NativeSocketError.AttemptsExhausted { attempted: usize, last: AttemptFailure }: NativeSocketError

The admitted connection attempt budget is exhausted.

Field attempted

pub attempted: usize

The number of native connect attempts already made.

Field last

pub last: AttemptFailure

The failure from the final attempted candidate.

TimeRangeError

NativeSocketError.TimeRangeError: NativeSocketError

The next positive wake time is not representable.

InvalidEndpoint

NativeSocketError.InvalidEndpoint { reason: InvalidEndpointReason, offset: usize, limit: usize }: NativeSocketError

An endpoint list or Unix pathname failed admission.

Field reason

pub reason: InvalidEndpointReason

The input admission rule that failed.

Field offset

pub offset: usize

The zero-based byte offset of the rejected pathname input.

Field limit

pub limit: usize

The admitted maximum for this input or transfer.

InvalidBindAddress

NativeSocketError.InvalidBindAddress { reason: InvalidBindReason, offset: usize }: NativeSocketError

A Unix bind pathname failed admission.

Field reason

pub reason: InvalidBindReason

The input admission rule that failed.

Field offset

pub offset: usize

The zero-based byte offset of the rejected pathname input.

PathTooLong

NativeSocketError.PathTooLong { length: usize, limit: usize }: NativeSocketError

The pathname and its terminator exceed native address capacity.

Field length

pub length: usize

The pathname or returned native address length in bytes.

Field limit

pub limit: usize

The admitted maximum for this input or transfer.

AddressInUse

NativeSocketError.AddressInUse: NativeSocketError

The requested local address is already in use.

InvalidNativeAddress

NativeSocketError.InvalidNativeAddress { family: i32, length: usize }: NativeSocketError

The returned native address has an invalid family or length.

Field family

pub family: i32

The native address family, or -1 when the header is too short.

Field length

pub length: usize

The pathname or returned native address length in bytes.

UnsupportedPeerAddress

NativeSocketError.UnsupportedPeerAddress { family: i32, length: usize }: NativeSocketError

The returned peer uses an unsupported address form.

Field family

pub family: i32

The native address family, or -1 when the header is too short.

Field length

pub length: usize

The pathname or returned native address length in bytes.

FamilyUnsupported

NativeSocketError.FamilyUnsupported: NativeSocketError

The requested address family is unsupported.

PermissionDenied

NativeSocketError.PermissionDenied: NativeSocketError

The operating system denied the operation.

ConnectionRefused

NativeSocketError.ConnectionRefused: NativeSocketError

The peer refused the connection.

NetworkUnreachable

NativeSocketError.NetworkUnreachable: NativeSocketError

The destination network is unreachable.

AddressUnavailable

NativeSocketError.AddressUnavailable: NativeSocketError

The requested address is unavailable.

SystemResources

NativeSocketError.SystemResources: NativeSocketError

The operating system cannot supply the required resources.

Timeout

NativeSocketError.Timeout: NativeSocketError

The supplied absolute deadline has been reached.

Closed

NativeSocketError.Closed: NativeSocketError

The descriptor is terminally closed.

WriteClosed

NativeSocketError.WriteClosed: NativeSocketError

The local write direction is closed; reads remain available.

InvalidTransferCount

NativeSocketError.InvalidTransferCount { operation: ByteIoOperation, count: usize, limit: usize }: NativeSocketError

A native success reported an impossible transfer count.

Field operation

pub operation: ByteIoOperation

The native or byte-I/O operation that failed.

Field count

pub count: usize

The invalid successful transfer count reported by the native operation.

Field limit

pub limit: usize

The admitted maximum for this input or transfer.

NativeFailure

NativeSocketError.NativeFailure { operation: NativeSocketOperation, errno: i32 }: NativeSocketError

A native boundary failed with the retained operation and error number.

Field operation

pub operation: NativeSocketOperation

The native or byte-I/O operation that failed.

Field errno

pub errno: i32

The native error number reported by the selected platform.

NativeSocket

pub struct NativeSocket

Namespace anchor for the selected native socket actor.

ConnectOptions

pub struct ConnectOptions

Finite readiness and attempt policy copied into one connection.

Associated function ConnectOptions.make

pub fn make(noDelay: bool, pollIntervalNanoseconds: u64, maxAttempts: usize) -> silk/result.Result<silk/native_socket.ConnectOptions, silk/native_socket.ConnectOptionsError>

Admits a 1..1,000,000,000ns interval and 1..1024 native attempts.

Associated function ConnectOptions.defaults

pub fn defaults() -> ConnectOptions

Selects Nagle, a one-millisecond readiness interval, and 64 attempts.

Method ConnectOptions.noDelay

pub fn noDelay<'life0>(self: &'life0 ConnectOptions) -> bool

Reports whether outbound TCP disables Nagle buffering.

Method ConnectOptions.pollInterval

pub fn pollInterval<'life0>(self: &'life0 ConnectOptions) -> u64

Returns the positive polling interval in nanoseconds.

Method ConnectOptions.maxAttempts

pub fn maxAttempts<'life0>(self: &'life0 ConnectOptions) -> usize

Returns the maximum number of native connection attempts.

ListenOptions

pub struct ListenOptions

Finite kernel admission and cooperative accept policy.

Associated function ListenOptions.make

pub fn make(kernelBacklog: usize, reuseAddress: bool, pollIntervalNanoseconds: u64) -> silk/result.Result<silk/native_socket.ListenOptions, silk/native_socket.ListenOptionsError>

Admits backlog 1..65535 and a 1..1,000,000,000ns polling interval.

Associated function ListenOptions.defaults

pub fn defaults() -> ListenOptions

Selects backlog 128, no address reuse, and a one-millisecond polling interval.

Method ListenOptions.kernelBacklog

pub fn kernelBacklog<'life0>(self: &'life0 ListenOptions) -> usize

Returns the requested kernel backlog limit.

Method ListenOptions.reuseAddress

pub fn reuseAddress<'life0>(self: &'life0 ListenOptions) -> bool

Reports whether listener creation enables SO_REUSEADDR.

Method ListenOptions.pollInterval

pub fn pollInterval<'life0>(self: &'life0 ListenOptions) -> u64

Returns the positive polling interval in nanoseconds.

UnixSocketPath

pub struct UnixSocketPath

One owned pathname spelling used by listener metadata.

Method UnixSocketPath.bytes

pub fn bytes<'life0>(self: &'life0 UnixSocketPath) -> &'life0 [u8]

Borrows the exact owned pathname spelling.

BoundAddress

pub union BoundAddress

The actual local address owned by a published listener.

Tcp

BoundAddress.Tcp { endpoint: Endpoint }: BoundAddress

An owned numeric TCP endpoint.

Field endpoint

pub endpoint: Endpoint

The owned numeric address and port.

Unix

BoundAddress.Unix { path: UnixSocketPath }: BoundAddress

An owned Unix-domain address.

Field path

pub path: UnixSocketPath

The owned Unix pathname spelling.

UnixPeerAddress

pub union UnixPeerAddress

The peer identity returned for one accepted Unix connection.

Unnamed

UnixPeerAddress.Unnamed: UnixPeerAddress

The peer has no bound pathname.

Pathname

UnixPeerAddress.Pathname { path: UnixSocketPath }: UnixPeerAddress

The peer has an owned pathname spelling.

Field path

pub path: UnixSocketPath

The owned Unix pathname spelling.

PeerAddress

pub union PeerAddress

The owned peer identity returned with one accepted connection.

Tcp

PeerAddress.Tcp { endpoint: Endpoint }: PeerAddress

An owned numeric TCP endpoint.

Field endpoint

pub endpoint: Endpoint

The owned numeric address and port.

Unix

PeerAddress.Unix { peer: UnixPeerAddress }: PeerAddress

An owned Unix-domain address.

Field peer

pub peer: UnixPeerAddress

The accepted peer identity.

Implementation Copy for ConnectOptionsError

impl Copy for ConnectOptionsError

Implementation Copy for AttemptFailure

impl Copy for AttemptFailure

Implementation Copy for NativeSocketError

impl Copy for NativeSocketError

Implementation Copy for ConnectOptions

impl Copy for ConnectOptions

Implementation Copy for ListenOptionsError

impl Copy for ListenOptionsError

Implementation Copy for ListenOptions

impl Copy for ListenOptions

Implementation Copy for UnixSocketPath

impl Copy for UnixSocketPath

Implementation Copy for BoundAddress

impl Copy for BoundAddress

Implementation Copy for UnixPeerAddress

impl Copy for UnixPeerAddress

Implementation Copy for PeerAddress

impl Copy for PeerAddress

Connection

pub struct Connection

One affine native descriptor lent only inside a connection callback.

Method Connection.phase

pub fn phase<'life0>(self: &'life0 Connection) -> ConnectionPhase

Returns the current descriptor lifecycle phase.

Method Connection.close

pub effect<'life0> fn close<'life0>(self: &'life0 mut Connection) -> () ! NativeSocketError

Explicitly closes this connection once. Scoped cleanup recovers this error.

Listener

pub struct Listener

One affine native listening descriptor and its validated local identity.

Method Listener.phase

pub fn phase<'life0>(self: &'life0 Listener) -> ListenerPhase

Returns the current descriptor lifecycle phase.

Method Listener.boundAddress

pub fn boundAddress<'life0>(self: &'life0 Listener) -> BoundAddress

Returns a copy of the actual local address recorded after listener creation.

Method Listener.close

pub effect<'life0> fn close<'life0>(self: &'life0 mut Listener) -> () ! NativeSocketError

Explicitly closes this listener once without unlinking a Unix pathname.

Accepted

pub struct Accepted

One independently owned accepted connection and peer identity.

Method Accepted.peer

pub fn peer<'life0>(self: &'life0 Accepted) -> PeerAddress

Returns a copy of the independently owned accepted peer identity.

Method Accepted.connectionPhase

pub fn connectionPhase<'life0>(self: &'life0 Accepted) -> ConnectionPhase

Returns the accepted connection lifecycle phase.

AcceptedView

pub struct AcceptedView<'a>

The higher-ranked loans available only inside one accepted-result scope.

Field connection

pub connection: &'a mut silk/native_socket.Connection

The exclusive connection loan valid only within this accepted-result scope.

Field peer

pub peer: &'a silk/native_socket.PeerAddress

The accepted peer identity.

AcceptedContext

pub interface AcceptedContext<A, E, ?CallbackRequirements, ?ContextRequirements>

Compile-time adapter from one owned context to an accepted-connection use.

Details

Implement this interface when the scoped use owns affine or once-callable state. The first row preserves caller-selected requirements and the second records requirements introduced by the concrete context. Selection adds no runtime service or requirement-row member: context is consumed once and the accepted loans remain independently higher-ranked.

Operation use

effect<'call> fn use<'call: 'call>(context: Self, view: &'call mut silk/native_socket.AcceptedView<'call>) -> A ! E ? CallbackRequirements | ContextRequirements

Consumes one owned context while using temporary accepted-connection loans.

listen

pub effect<'static> fn listen(endpoint: Endpoint, options: ListenOptions) -> Listener ! NativeSocketError

Creates one IPv4 or IPv6 listener and publishes its actual bound endpoint.

listenUnix

pub effect<'life0> fn listenUnix<'life0>(path: &'life0 [u8], options: ListenOptions) -> Listener ! NativeSocketError

Creates one pathname-Unix listener without unlinking before bind or after close.

accept

pub effect<'life0> fn accept<'life0>(listener: &'life0 mut silk/native_socket.Listener, deadline: silk/option.Option<silk/system_clock.Instant>) -> Accepted ! NativeSocketError ? &mut MonotonicClock

Accepts one independently owned connection under an unchanged absolute deadline.

withListener

pub effect<'env> fn withListener<'env, A, E, ?CallbackRequirements>(listener: Listener, callback: for<'call> once fn<'env>(&'call mut silk/native_socket.Listener) -> once Effect<'call; A ! E ? CallbackRequirements>) -> A ! E ? CallbackRequirements

Consumes one listener and lends it through a nonparking structured finalizer.

withAccepted

pub effect<'env> fn withAccepted<'env, A, E, ?CallbackRequirements>(accepted: Accepted, callback: for<'call> once fn<'env>(&'call mut silk/native_socket.AcceptedView<'call>) -> once Effect<'call; A ! E ? CallbackRequirements>) -> A ! E ? CallbackRequirements where CallbackRequirements in Without<CallbackRequirements, &ByteDuplex>

Consumes one accepted owner and lends its connection plus borrowed peer metadata.

withAcceptedContext

pub effect<'env> fn withAcceptedContext<A, E, ?CallbackRequirements, ?ContextRequirements, C: 'env, 'env>(accepted: Accepted, context: C) -> A ! E ? CallbackRequirements | ContextRequirements where CallbackRequirements in Without<CallbackRequirements, &ByteDuplex>, ContextRequirements in Without<ContextRequirements, &ByteDuplex>

Consumes one compile-time-selected context with temporary accepted-connection loans.

Details

The context is captured by the once-callable protected use and consumed exactly once. Structured success, typed failure, and cancellation close the connection once; close failure never replaces the protected outcome.

connectResolvedOwned

pub effect<'life0> fn connectResolvedOwned<'life0>(endpoints: &'life0 [silk/network_address.Endpoint], options: ConnectOptions, deadline: silk/option.Option<silk/system_clock.Instant>) -> Connection ! NativeSocketError ? &mut MonotonicClock

Connects an ordered nonempty numeric endpoint slice and returns one affine provider owner.

connectUnixOwned

pub effect<'life0> fn connectUnixOwned<'life0>(path: &'life0 [u8], options: ConnectOptions, deadline: silk/option.Option<silk/system_clock.Instant>) -> Connection ! NativeSocketError ? &mut MonotonicClock

Connects one absolute pathname Unix socket and returns one affine provider owner.

connectResolved

pub effect<'env1> fn connectResolved<'env: 'env1, A, E, ?CallbackRequirements, 'life4: 'env1, 'env1>(endpoints: &'life4 [silk/network_address.Endpoint], options: ConnectOptions, deadline: silk/option.Option<silk/system_clock.Instant>, callback: for<'call> once fn<'env>(&'call mut silk/native_socket.Connection) -> once Effect<'call; A ! E ? CallbackRequirements>) -> A ! E | NativeSocketError ? CallbackRequirements | &mut MonotonicClock where CallbackRequirements in Without<CallbackRequirements, &ByteDuplex>

Connects an ordered nonempty numeric endpoint slice and lends the owned provider in one scope.

connectUnix

pub effect<'env1> fn connectUnix<'env: 'env1, A, E, ?CallbackRequirements, 'life4: 'env1, 'env1>(path: &'life4 [u8], options: ConnectOptions, deadline: silk/option.Option<silk/system_clock.Instant>, callback: for<'call> once fn<'env>(&'call mut silk/native_socket.Connection) -> once Effect<'call; A ! E ? CallbackRequirements>) -> A ! E | NativeSocketError ? CallbackRequirements | &mut MonotonicClock where CallbackRequirements in Without<CallbackRequirements, &ByteDuplex>

Connects one absolute pathname Unix socket and lends the owned provider in one scope.

Implementation ByteDuplex for Connection

impl ByteDuplex for Connection

Operation readSomeRaw

readSomeRaw = Connection.readConnection

Operation writeSomeRaw

writeSomeRaw = Connection.writeConnection

Operation flushRaw

flushRaw = Connection.flushConnection

Operation shutdownWriteRaw

shutdownWriteRaw = Connection.shutdownConnection

Operation closeRaw

closeRaw = Connection.closeByteConnection