gdDocumentation0.8.0

API reference

GDTCPConn

Concurrency-safe TCP or TLS byte stream with FIFO reads and writes, deadlines, Close wakeups, and addresses.

Methods

read

read(max: int = 65536) -> PackedByteArray, Err

Start reading, suspending only this caller until bytes arrive.

Parameters

NameTypeDefaultDescription
maxint65536Maximum bytes requested by one receive operation.

Return value

PackedByteArray, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_async

read_async(max: int = 65536) -> await PackedByteArray, Err

Start reading, suspending only this caller until bytes arrive.

Parameters

NameTypeDefaultDescription
maxint65536Maximum bytes requested by one receive operation.

Return value

await PackedByteArray, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

write

write(data: PackedByteArray) -> int, Err

Start writing, suspending only this caller until all bytes reach the kernel.

Parameters

NameTypeDefaultDescription
dataPackedByteArrayRequiredInput data in the representation shown by the parameter type.

Return value

int, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

write_async

write_async(data: PackedByteArray) -> await int, Err

Start writing, suspending only this caller until all bytes reach the kernel.

Parameters

NameTypeDefaultDescription
dataPackedByteArrayRequiredInput data in the representation shown by the parameter type.

Return value

await int, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

start_tls

start_tls(host: String, opts: Dictionary = {  }) -> GDTCPConn, Err

Upgrade a quiet plaintext connection to verified TLS.

Upgrade an idle plaintext TCP connection to verified TLS on the same socket. Use the returned connection after success.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

GDTCPConn, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

start_tls_async

start_tls_async(host: String, opts: Dictionary = {  }) -> await GDTCPConn, Err

Upgrade a quiet plaintext connection to verified TLS.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

await GDTCPConn, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

set_deadline

set_deadline(seconds: float) -> Err

Set both I/O deadlines in seconds from now.

Parameters

NameTypeDefaultDescription
secondsfloatRequiredDeadline setting in seconds; see this method for relative-time and clearing semantics.

Return value

Err

Errors

Returns an Err object directly, not a value-and-error pair. An absent error is null; inspect the method description to distinguish creation, lookup, and stored failure.

set_read_deadline

set_read_deadline(seconds: float) -> Err

Set the read deadline, including reads already waiting.

Parameters

NameTypeDefaultDescription
secondsfloatRequiredDeadline setting in seconds; see this method for relative-time and clearing semantics.

Return value

Err

Errors

Returns an Err object directly, not a value-and-error pair. An absent error is null; inspect the method description to distinguish creation, lookup, and stored failure.

set_write_deadline

set_write_deadline(seconds: float) -> Err

Set the write deadline, including writes already waiting.

Parameters

NameTypeDefaultDescription
secondsfloatRequiredDeadline setting in seconds; see this method for relative-time and clearing semantics.

Return value

Err

Errors

Returns an Err object directly, not a value-and-error pair. An absent error is null; inspect the method description to distinguish creation, lookup, and stored failure.

local_addr

local_addr() -> Dictionary

Return the local TCP address.

Parameters

No parameters.

Return value

Dictionary

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

remote_addr

remote_addr() -> Dictionary

Return the remote TCP address.

Parameters

No parameters.

Return value

Dictionary

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

connection_state

connection_state() -> Dictionary

Expose TLS handshake state using standard ConnectionState names.

Inspect published handshake_complete, server_name, negotiated_protocol, and numeric TLS version without accessing active worker state. Version is zero before negotiation; 771 and 772 denote TLS 1.2 and 1.3.

Parameters

No parameters.

Return value

Dictionary

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

is_open

is_open() -> bool

Check whether the TCP stream permits I/O.

Parameters

No parameters.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

close

close() -> void

Close the TCP stream and wake every pending operation.

Parameters

No parameters.

Return value

void

No value is returned.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.