Object and construction

• TcpConnection is one object with an atomic Nat32 state word, one socket handle, one read dispatcher.Context, one write dispatcher.Context, and callback storage.
• INIT sets the state word to 0n32. Default construction therefore creates an unconnected object; this module has no makeTcpConnection helper.
• The state bits are IN_DIE=0x00000001n32, IN_IS_CONNECTED=0x00000002n32, IN_SET=0x00000004n32, IN_CONNECT=0x00000008n32, IN_CANCEL_CONNECT=0x00000010n32, IN_DISCONNECT=0x00000020n32, IN_READ=0x00000040n32, IN_CANCEL_READ=0x00000080n32, IN_WRITE=0x00000100n32, IN_CANCEL_WRITE=0x00000200n32, IN_ON_CONNECT_EVENT=0x00000400n32, IN_ON_READ_EVENT=0x00000800n32, IN_ON_WRITE_EVENT=0x00001000n32, CONNECTING=0x00002000n32, CONNECTED=0x00004000n32, READING=0x00008000n32, and WRITING=0x00010000n32.
• connect creates a socket and starts ConnectEx. setConnection is the handoff used by windows/TcpAcceptor after an accepted socket has completed.
• ConnectEx is an exported FN_CONNECTEXRef slot. connect resolves it through WSAIoctl when it is nil.
• The module uses the completion port exported by windows/dispatcher; it does not create a fiber or a worker thread.
• DIE atomically enters its destruction state and asserts that the state was zero. Active connect/read/write operations and connected handles must be completed, canceled, or disconnected before destruction.

Methods

Completion and callback model

• connect, read, and write return before completion. Their callback fields are stored in Function objects and are called by dispatcher completion handlers.
• The read and write contexts embed one OVERLAPPED each, store self as their context, and install the source's read or write event wrapper. The completion key is zero for these overlapped socket entries.
• Connect completion checks WSAGetOverlappedResult, updates the socket with SO_UPDATE_CONNECT_CONTEXT, and then marks the object CONNECTED. The connect callback is stored in the write callback slot.
• Read completion passes the transferred byte count as Int32 and a result reference to onRead. Write completion passes a result reference to onWrite.
• ERROR_OPERATION_ABORTED becomes result "canceled". Other completion errors are reported as "ConnectEx failed, result=", "WSARecv failed, result=", or "WSASend failed, result=" followed by the error code.
• This differs from sync/TcpConnection: the sync variant uses fibers, its read returns a byte count directly, and it provides readString; this module returns initiation strings and reports completion through callbacks.
• Dispatch until the operation's completion callback has run before leaving the connection's scope. An empty immediate result means initiation succeeded, not completion; call disconnect only after successful completion has made the state CONNECTED.

Ownership and threading

• The object owns connection: Natx after successful connect completion or setConnection. disconnect closes that handle.
• setConnection is the accepted-socket handoff; the acceptor must not close the handle after handing it to the connection object.
• State transitions use the source's acquire/release atomic operations. Invalid concurrent or out-of-order calls trigger the source assertions.
• The module creates no fiber and no worker thread. The thread that calls dispatcher.dispatch or dispatcher.tryDispatch runs the completion callback.
• The source warns that callers must synchronize cancellation with the return from connect, read, or write. The connect cancellation path also handles a callback race by reposting completion.

Results and errors

• connect reports immediate setup errors beginning with socket failed, result=, setsockopt failed, result=, bind failed, result=, WSAIoctl failed, result=, CreateIoCompletionPort failed, result=, or ConnectEx failed, result=.
• read reports immediate receive errors as WSARecv failed, result=; write reports immediate send errors as WSASend failed, result=.
• Cancellation returns FALSE when no matching operation is active or when CancelIoEx fails. A failed cancellation other than ERROR_NOT_FOUND is printed as a diagnostic.
• A failed closesocket prints a LEAK: closesocket failed, result= diagnostic. Invalid state and invalid span/callback forms use the source assertions or static argument error.

Examples

Windows dispatcher connection

"Function"              use
"String"                use
"control"               use
"windows/TcpConnection" use
"windows/dispatcher"    use

{} Int32 {} [
  connection: TcpConnection;
  handled: FALSE dynamic;
  onConnect: ({result: String Ref;} {} {}) Function;
  callback: [result:;];
  @callback @onConnect.assign
  result: 0x7F000001n32 6615n16 @onConnect @connection.connect;
  [result.size 0 =] "connect failed" ensure
  [handled ~] [dispatcher.tryDispatch @handled set] while
  [@connection.isConnected] "connect did not complete" ensure
  @connection.disconnect
  0
] "main" exportFunction

See also

• windows/dispatcher: Windows completion-port dispatcher and callback posting helpers.
• windows/TcpAcceptor: Windows completion-port TCP acceptor with asynchronous callbacks.
• sync/TcpConnection: Connected TCP stream with buffered read, string read, write, and shutdown operations.
• windows/ws2_32: Winsock2 declarations for sockets, overlapped I/O, and address-resolution helpers.