Chronos

https://status-im.github.io/nim-chronos
Admin
Chronos is a Nim library implementing async/await paradigm with asynchronous socket and process I/O,...
Tokens:196,815
Snippets:1,900
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### start

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Starts the stream server.

```APIDOC
## start

### Description
Starts `server`.

### Method
`start`

### Parameters
- `server` (StreamServer) - The stream server to start.

### Raises
- `TransportOsError`
```

--------------------------------

### Install mdBook and Preprocessors

Source: https://status-im.github.io/nim-chronos/book.html

Install mdBook and its associated preprocessor crates using cargo. This command installs specific versions of mdbook, mdbook-toc, mdbook-open-on-gh, and mdbook-admonish.

```bash
cargo install mdbook@0.4.36 mdbook-toc@0.14.1 mdbook-open-on-gh@2.4.3 mdbook-admonish@0.14.0
```

--------------------------------

### Install Chronos using Nimble

Source: https://status-im.github.io/nim-chronos

Install the chronos library using the nimble package manager.

```nim
nimble install chronos
```

--------------------------------

### Install mdBook and Preprocessors with Cargo-Binstall

Source: https://status-im.github.io/nim-chronos/print.html

Install mdBook and its associated preprocessor crates using cargo-binstall, an alternative for users who prefer not to install the full Rust toolchain.

```bash
cargo-binstall mdbook@0.4.36 mdbook-toc@0.14.1 mdbook-open-on-gh@2.4.3 mdbook-admonish@0.14.0

```

--------------------------------

### Start Stream Server

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Starts the stream server. May raise TransportOsError.

```nim
proc start(server: StreamServer) {....raises: [TransportOsError], raises: [],
                                   tags: [RootEffect].}
```

--------------------------------

### Multithreading with ThreadSignalPtr

Source: https://status-im.github.io/nim-chronos/print.html

Illustrates using ThreadSignalPtr for inter-thread communication. This example shows how to create a shared context, start a worker thread that signals completion, and wait for that signal in the main async procedure.

```nim
import chronos, chronos/threadsync
import os

type Context = object
  # Context allocated by `createShared` should contain no garbage-collected
  # types!
  signal: ThreadSignalPtr
  value: int

proc myThread(ctx: ptr Context) {.thread.} =
  echo "Doing some work in a thread"
  sleep(3000)
  ctx.value = 42
  echo "Done, firing the signal"
  discard ctx.signal.fireSync().expect("correctly initialized signal should not fail")

proc main() {.async.} =
  let
    signal = ThreadSignalPtr.new().expect("free file descriptor for signal")
    context = createShared(Context)
  context.signal = signal

  var thread: Thread[ptr Context]

  echo "Starting thread"
  createThread(thread, myThread, context)

  await signal.wait()

  echo "Work done: ", context.value

  joinThread(thread)

  signal.close().expect("closing once works")
  deallocShared(context)

waitFor main()
```

--------------------------------

### Install mdBook and Preprocessors with Cargo

Source: https://status-im.github.io/nim-chronos/print.html

Install mdBook and its associated preprocessor crates using the Rust cargo command. This is the recommended method if you have a working Rust toolchain.

```bash
cargo install mdbook@0.4.36 mdbook-toc@0.14.1 mdbook-open-on-gh@2.4.3 mdbook-admonish@0.14.0

```

--------------------------------

### Install mdBook with cargo-binstall

Source: https://status-im.github.io/nim-chronos/book.html

Alternative installation method for mdBook and preprocessors using cargo-binstall, suitable if Rust is not fully set up. This command installs specific versions of the crates.

```bash
cargo-binstall mdbook@0.4.36 mdbook-toc@0.14.1 mdbook-open-on-gh@2.4.3 mdbook-admonish@0.14.0
```

--------------------------------

### Start Stream Server (Result Type)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Starts the stream server, returning a Result type that indicates success or an OSErrorCode.

```nim
proc start2(server: StreamServer): Result[void, OSErrorCode] {....raises: [],
    tags: [RootEffect].}
```

--------------------------------

### Get Interfaces

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/osnet.html

Returns a list of all available network interfaces.

```APIDOC
## proc getInterfaces(): seq[NetworkInterface]

### Description
Return list of available interfaces.

### Signature
proc getInterfaces(): seq[NetworkInterface]
```

--------------------------------

### start2

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Starts the stream server, returning a Result type for error handling.

```APIDOC
## start2

### Description
Starts `server`.

### Method
`start2`

### Parameters
- `server` (StreamServer) - The stream server to start.

### Returns
- `Result[void, OSErrorCode]` - A Result indicating success or an OS error code.
```

--------------------------------

### handles: getSockOpt

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets a socket option value.

```APIDOC
## handles: getSockOpt

### Description
Gets a socket option value.

### Signature
`proc getSockOpt(socket: AsyncFD; level, optname: int; value: var int): bool`
```

--------------------------------

### Build and Serve Local Documentation

Source: https://status-im.github.io/nim-chronos/print.html

Build and serve the documentation locally using mdBook. This command will watch for changes and automatically rebuild and refresh the browser.

```bash
mdbook serve --hostname:0.0.0.0 docs

```

--------------------------------

### posixSpawnAttrGetSigDefault

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the signal default settings from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetSigDefault

### Description
Gets the signal default settings from a posix_spawn attribute object.

### Method
posixSpawnAttrGetSigDefault

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var Sigset) - Description: Pointer to a Sigset structure to store the retrieved signal default settings.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### Serve Local Documentation

Source: https://status-im.github.io/nim-chronos/book.html

Build and serve the documentation locally using mdbook serve. This command makes the documentation accessible at localhost:3000 and automatically rebuilds and refreshes on source changes.

```bash
mdbook serve --hostname:0.0.0.0 docs
```

--------------------------------

### posixSpawnFileActionsInit

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Initializes a posix_spawn file actions object.

```APIDOC
## posixSpawnFileActionsInit

### Description
Initializes a posix_spawn file actions object.

### Method
posixSpawnFileActionsInit

### Parameters
- **a1** (var PosixSpawnFileActions) - Description: The file actions object to initialize.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### `init` (typedesc[IpNet], string)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP network from its string representation.

```APIDOC
## `init` (typedesc[IpNet], string)

### Description
Initializes an IP Network from its string representation in the format <address>/<prefix length> or <address>/<netmask address>.

### Method
`init`

### Parameters
- **t** (typedesc[IpNet]) - Type descriptor for IpNet.
- **network** (string) - The string representation of the IP network.

### Response
- **IpNet** - The initialized IP network.

### Raises
- **TransportAddressError** - If the network string is invalid.
```

--------------------------------

### init

Source: https://status-im.github.io/nim-chronos/api/chronos/bipbuffer.html

Creates and initializes a new BipBuffer with a specified size.

```APIDOC
## init

### Description
Creates and initializes a new BipBuffer with a specified size.

### Signature
proc init(t: typedesc[BipBuffer]; size: int): BipBuffer
```

--------------------------------

### Get Available Network Interfaces

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/osnet.html

Returns a sequence of all available NetworkInterface objects on the system.

```nim
proc getInterfaces(): seq[NetworkInterface] {"....raises: [], raises: [], tags: [].}

```

--------------------------------

### Comprehensive Middleware Example

Source: https://status-im.github.io/nim-chronos/http_server_middleware.html

Illustrates a complete middleware handler with various conditional logic for handling different request paths. It shows error checking, request modification, IP-based access control, and request dropping.

```nim
proc middlewareHandler(
    middleware: HttpServerMiddlewareRef,
    reqfence: RequestFence,
    nextHandler: HttpProcessCallback2
): Future[HttpResponseRef] {.async: (raises: [CancelledError]).}
  if reqfence.isErr():
    # We dont know or do not want to handle failed requests, so we call next handler.
    return await nextHandler(reqfence)
  let request = reqfence.get()
  if request.uri.path == "/path/we/able/to/respond":
    try:
      # Sending some response.
      await request.respond(Http200, "TEST")
    except HttpWriteError as exc:
      # We could also return default response for exception or other types of error.
      defaultResponse(exc)
  elif request.uri.path == "/path/for/rewrite":
    # We going to modify request object for this request, next handler will receive it with different request path.
    let res = request.updateRequest("/path/to/new/location")
    if res.isErr():
      return defaultResponse(res.error)
    await nextHandler(reqfence)
  elif request.uri.path == "/restricted/path":
    if request.remote().isNone():
      # We can't obtain remote address, so we force HTTP server to respond with `401 Unauthorized` status code.
      return codeResponse(Http401)
    if $(request.remote().get()).startsWith("127.0.0.1"):
      # Remote peer's address starts with "127.0.0.1", sending proper response.
      await request.respond(Http200, "AUTHORIZED")
    else:
      # Force HTTP server to respond with `403 Forbidden` status code.
      codeResponse(Http403)
  elif request.uri.path == "/blackhole":
    # Force HTTP server to drop connection with remote peer.
    dropResponse()
  else:
    # All other requests should be handled by somebody else.
    await nextHandler(reqfence)
```

--------------------------------

### timer: now

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the current time as a Moment object.

```APIDOC
## timer: now

### Description
Gets the current time as a Moment object.

### Signature
`timer: now(t: typedesc[Moment]): Moment`
```

--------------------------------

### init

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/osnet.html

Initializes an interface address with specified parameters.

```APIDOC
## init

### Description
Initializes an interface address with specified parameters.

### Signature
init(ift: typedesc[InterfaceAddress]; address: TransportAddress; prefix: int): InterfaceAddress

### Parameters
#### Path Parameters
- **ift** (typedesc[InterfaceAddress]) - Required - The type descriptor for the interface address.
- **address** (TransportAddress) - Required - The transport address to initialize with.
- **prefix** (int) - Required - The prefix length for the address.

### Returns
An initialized `InterfaceAddress` object.
```

--------------------------------

### handles: getSocketError

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the error code from a socket.

```APIDOC
## handles: getSocketError

### Description
Gets the error code from a socket.

### Signature
`proc getSocketError(socket: AsyncFD; err: var int): bool`
```

--------------------------------

### `init` (typedesc[IpNet], TransportAddress, IpMask)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP network using a host transport address and an IP mask.

```APIDOC
## `init` (typedesc[IpNet], TransportAddress, IpMask)

### Description
Initializes an IP Network using the host address `host` and the network mask `mask`.

### Method
`init`

### Parameters
- **t** (typedesc[IpNet]) - Type descriptor for IpNet.
- **host** (TransportAddress) - The host address.
- **mask** (IpMask) - The network mask.

### Response
- **IpNet** - The initialized IP network.
```

--------------------------------

### Get Best Route

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/osnet.html

Returns the best applicable OS route for connecting to a given address.

```APIDOC
## proc getBestRoute(address: TransportAddress): Route

### Description
Return best applicable OS route, which will be used for connecting to address `address`.

### Signature
proc getBestRoute(address: TransportAddress): Route
```

--------------------------------

### asyncengine: getGlobalDispatcher

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the global asynchronous dispatcher.

```APIDOC
## asyncengine: getGlobalDispatcher

### Description
Gets the global asynchronous dispatcher.

### Signature
`proc getGlobalDispatcher(): PDispatcher`
```

--------------------------------

### remoteAddress

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/datagram.html

Gets the remote address of the datagram transport.

```APIDOC
## remoteAddress

### Description
Returns the remote transport address associated with the datagram transport.

### Signature
`remoteAddress(transp: DatagramTransport): TransportAddress`

### Parameters
* `transp` (DatagramTransport) - The datagram transport instance.

### Returns
* `TransportAddress` - The remote address of the transport.
```

--------------------------------

### `init` (typedesc[IpMask], AddressFamily, int)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP mask from a prefix length and IP family.

```APIDOC
## `init` (typedesc[IpMask], AddressFamily, int)

### Description
Initializes an IP mask of the specified IP family from a given prefix length.

### Method
`init`

### Parameters
- **t** (typedesc[IpMask]) - Type descriptor for IpMask.
- **family** (AddressFamily) - The IP address family (e.g., IPv4, IPv6).
- **prefix** (int) - The prefix length for the mask.

### Response
- **IpMask** - The initialized IP mask.
```

--------------------------------

### Initialize IpNet from Host Address and Mask

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IpNet using a host address and an IpMask.

```nim
proc init(t: typedesc[IpNet]; host: TransportAddress; mask: IpMask): IpNet {.inline, ...raises: [].}
```

--------------------------------

### localAddress

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/datagram.html

Gets the local address of the datagram transport.

```APIDOC
## localAddress DatagramTransport

### Description
Gets the local address of the datagram transport.

### Method
(Implicitly a procedure call, not HTTP)

### Parameters
* **transp** (DatagramTransport) - The datagram transport.

### Returns
* TransportAddress - The local transport address.
```

--------------------------------

### posixSpawnAttrGetFlags

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the flags from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetFlags

### Description
Gets the flags from a posix_spawn attribute object.

### Method
posixSpawnAttrGetFlags

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var cshort) - Description: Pointer to a short integer to store the retrieved flags.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### `init` (typedesc[IpNet], TransportAddress, int)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP network using a host transport address and a prefix length.

```APIDOC
## `init` (typedesc[IpNet], TransportAddress, int)

### Description
Initializes an IP Network using the host address `host` and the prefix length `prefix`.

### Method
`init`

### Parameters
- **t** (typedesc[IpNet]) - Type descriptor for IpNet.
- **host** (TransportAddress) - The host address.
- **prefix** (int) - The prefix length.

### Response
- **IpNet** - The initialized IP network.
```

--------------------------------

### start2

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Starts a StreamServer and returns a Result indicating success or an OSErrorCode on failure. This function is part of the stream module.

```APIDOC
## start2

### Description
Starts a StreamServer and reports success or failure.

### Method
N/A (SDK function)

### Endpoint
N/A (SDK function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (void)
Indicates successful start.

#### Error Response (OSErrorCode)
Details of the operating system error encountered during startup.

#### Response Example
N/A
```

--------------------------------

### Future Value and Error Retrieval

Source: https://status-im.github.io/nim-chronos/api/chronos/futures.html

These functions are used to retrieve the result of a future. Use `error` to get the error if the future failed, and `value` to get the result if the future completed successfully. Note that `value` for `Future[void]` does not return a value but checks for completion.

```APIDOC
## error

### Description
Returns the error of a future. Returns `nil` if the future did not fail. Use `readError` for a version that raises a catchable error when the future has not failed.

### Function Signature
`func error(future: FutureBase): ref CatchableError`

## value (for Future[void])

### Description
Checks if a completed future with a `void` type has completed. It does not return a value. Raises `Defect` when `fut.completed()` is `false`. See `read` for a version that raises a catchable error when the future has not completed.

### Function Signature
`func value(future: Future[void])`

## value (for Future[T] where T is not void)

### Description
Returns the value of a completed future. Raises `Defect` when `fut.completed()` is `false`. See `read` for a version that raises a catchable error when the future has not completed.

### Function Signature
`func value[T: not void](future: Future[T]): lent T`
```

--------------------------------

### remoteAddress

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the remote address of a datagram or stream transport.

```APIDOC
## remoteAddress

### Description
Gets the remote address of a datagram or stream transport.

### Method
TransportAddress

### Parameters
#### Path Parameters
- `transp` (DatagramTransport) - Description not available
- `transp` (StreamTransport) - Description not available

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `TransportAddress` - Description not available

#### Response Example
None
```

--------------------------------

### `init` (typedesc[IpNet], TransportAddress, TransportAddress)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP network using host and mask transport addresses.

```APIDOC
## `init` (typedesc[IpNet], TransportAddress, TransportAddress)

### Description
Initializes an IP Network using the host address `host` and the network mask address `mask`. Note that `host` and `mask` must be from the same IP family.

### Method
`init`

### Parameters
- **t** (typedesc[IpNet]) - Type descriptor for IpNet.
- **host** (TransportAddress) - The host address.
- **mask** (TransportAddress) - The network mask address.

### Response
- **IpNet** - The initialized IP network.
```

--------------------------------

### handles: getSocketError2

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the socket error, returning a Result.

```APIDOC
## handles: getSocketError2

### Description
Gets the socket error, returning a Result.

### Signature
`proc getSocketError2(socket: AsyncFD): Result[cint, OSErrorCode]`
```

--------------------------------

### Initialize InternalRaisesFuture (Basic)

Source: https://status-im.github.io/nim-chronos/api/chronos/internal/raisesfutures.html

A template to create a new pending `InternalRaisesFuture`. It is recommended to specify `fromProc` for debugging purposes.

```nim
template init[T, E](F: type InternalRaisesFuture[T, E];
                    fromProc: static[string] = ""): F:type
```

--------------------------------

### Get Length of AsyncEventQueue

Source: https://status-im.github.io/nim-chronos/api/chronos/asyncsync.html

Returns the number of elements in an AsyncEventQueue.

```nim
proc len(ab: AsyncEventQueue): int {....raises: [], raises: [].}
```

--------------------------------

### posixSpawnAttrGetSigMask

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the signal mask from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetSigMask

### Description
Gets the signal mask from a posix_spawn attribute object.

### Method
posixSpawnAttrGetSigMask

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var Sigset) - Description: Pointer to a Sigset structure to store the retrieved signal mask.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### Initialize IpMask from Prefix

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IpMask for a given IP family and prefix length.

```nim
proc init(t: typedesc[IpMask]; family: AddressFamily; prefix: int): IpMask {.raises: [].}
```

--------------------------------

### `init` (typedesc[IpMask], string)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP mask from its hexadecimal string representation.

```APIDOC
## `init` (typedesc[IpMask], string)

### Description
Initializes an IP mask using its hexadecimal string representation `netmask`. If the `netmask` is invalid, the resulting `IpMask.family` will be set to `AddressFamily.None`.

### Method
`init`

### Parameters
- **t** (typedesc[IpMask]) - Type descriptor for IpMask.
- **netmask** (string) - The hexadecimal string representation of the network mask.

### Response
- **IpMask** - The initialized IP mask.
```

--------------------------------

### posixSpawnAttrGetSchedPolicy

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the scheduling policy from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetSchedPolicy

### Description
Gets the scheduling policy from a posix_spawn attribute object.

### Method
posixSpawnAttrGetSchedPolicy

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var cint) - Description: Pointer to an integer to store the retrieved scheduling policy.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### posixSpawnAttrGetSchedParam

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the scheduling parameters from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetSchedParam

### Description
Gets the scheduling parameters from a posix_spawn attribute object.

### Method
posixSpawnAttrGetSchedParam

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var SchedParam) - Description: Pointer to a SchedParam structure to store the retrieved scheduling parameters.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### Get Tracker Counter

Source: https://status-im.github.io/nim-chronos/api/chronos/internal/asyncengine.html

Returns the value of a counter by its name.

```nim
proc getTrackerCounter(name: string): TrackerCounter {.noinit, ...raises: [], tags: [].}
```

--------------------------------

### Early Exception Handling with try/except

Source: https://status-im.github.io/nim-chronos/error_handling.html

Shows how to use a `try` block around an `await` to catch exceptions from an async procedure sooner, allowing subsequent code to be reachable.

```nim
proc p3() {.async.} =
  let
    fut1 = p1()
    fut2 = p2()
  try:
    await fut1
  except CachableError:
    echo "p1() failed: ", fut1.error.name, ": ", fut1.error.msg
  echo "reachable code here"
  await fut2
```

--------------------------------

### getSockOpt

Source: https://status-im.github.io/nim-chronos/api/chronos/handles.html

Gets a socket option by level and option name.

```APIDOC
## getSockOpt (int overload)

### Description
Gets a socket option by level and option name, expecting an integer value.

### Parameters
* **socket** (AsyncFD) - The asynchronous file descriptor for the socket.
* **level** (int) - The option level.
* **optname** (int) - The option name.
* **value** (var int) - A variable to store the integer option value.

### Returns
A boolean indicating whether the option was successfully retrieved.
```

```APIDOC
## getSockOpt (pointer overload)

### Description
Gets a socket option by level and option name, expecting a pointer value.

### Parameters
* **socket** (AsyncFD) - The asynchronous file descriptor for the socket.
* **level** (int) - The option level.
* **optname** (int) - The option name.
* **value** (var pointer) - A variable to store the pointer option value.
* **valuelen** (var int) - A variable to store the length of the option value.

### Returns
A boolean indicating whether the option was successfully retrieved.
```

--------------------------------

### Initialize IpNet from Host Address and Prefix

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IpNet using a host address and a prefix length.

```nim
proc init(t: typedesc[IpNet]; host: TransportAddress; prefix: int): IpNet {.inline, ...raises: [].}
```

--------------------------------

### Create Stream Server with Callback

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Initializes a stream server bound to a specific address, using a callback for new client connections. This overload is deprecated for callbacks that may raise exceptions.

```nim
proc createStreamServer(host: TransportAddress; cbproc: StreamCallback;
                        flags: set[ServerFlags] = {};
                        sock: AsyncFD = asyncInvalidSocket;
                        backlog: int = DefaultBacklogSize;
                        bufferSize: int = DefaultStreamBufferSize;
                        child: StreamServer = nil;
                        init: TransportInitCallback = nil; udata: pointer = nil;
                        dualstack = DualStackType.Auto): StreamServer {. 
    ...raises: [TransportOsError], deprecated: "Callback must not raise exceptions, annotate with {.async: (raises: []).}",
    raises: [], tags: [RootEffect].}

```

--------------------------------

### Get Future ID

Source: https://status-im.github.io/nim-chronos/api/chronos/futures.html

Retrieves the unique identifier for a future.

```nim
template id(fut: FutureBase): uint
```

--------------------------------

### Create Stream Server with Flags

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Initializes a stream server with specified flags, allowing for custom socket configurations. This overload is suitable when a callback is not immediately required or managed differently.

```nim
proc createStreamServer(host: TransportAddress; flags: set[ServerFlags] = {};
                        sock: AsyncFD = asyncInvalidSocket;
                        backlog: int = DefaultBacklogSize;
                        bufferSize: int = DefaultStreamBufferSize;
                        child: StreamServer = nil;
                        init: TransportInitCallback = nil; udata: pointer = nil;
                        dualstack = DualStackType.Auto): StreamServer {. 
    ...raises: [TransportOsError], raises: [], tags: [RootEffect].}

```

--------------------------------

### ipnet: init

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Constructors for creating IpMask and IpNet objects with different parameters.

```APIDOC
## ipnet: init

### Description
Constructors for creating IpMask and IpNet objects.

### Method
Various (constructor)

### Parameters

#### IpMask Constructors:
- `t: typedesc[IpMask], value: int64, precision: Duration`
- `t: typedesc[IpMask], family: AddressFamily, prefix: int`
- `t: typedesc[IpMask], netmask: string`
- `t: typedesc[IpMask], netmask: TransportAddress`

#### IpNet Constructors:
- `t: typedesc[IpNet], network: string`
- `t: typedesc[IpNet], host: TransportAddress, prefix: int`
- `t: typedesc[IpNet], host: TransportAddress, mask: IpMask`
- `t: typedesc[IpNet], host, mask: TransportAddress`
```

--------------------------------

### Get Future State

Source: https://status-im.github.io/nim-chronos/api/chronos/futures.html

Retrieves the current state of a future.

```nim
func state(future: FutureBase): FutureState {....raises: [], tags: [].}
```

--------------------------------

### posixSpawnp

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Spawns a new process using the specified executable and actions.

```APIDOC
## posixSpawnp

### Description
Spawns a new process using the given executable, file actions, attributes, and arguments.

### Method
Not Applicable (This is a procedure call)

### Endpoint
Not Applicable

### Parameters
* **a1** (var Pid) - A variable to store the process ID of the new process.
* **a2** (cstring) - The path to the executable to spawn.
* **a3** (var PosixSpawnFileActions) - File actions to be performed in the child process before execution.
* **a4** (var PosixSpawnAttr) - Attributes for the new process.
* **a5** (cstringArray) - An array of strings representing the argument list for the new process (argv).
* **a6** (cstringArray) - An array of strings representing the environment list for the new process (envp).

### Request Example
```nim
var pid: Pid
var actions: PosixSpawnFileActions
var attr: PosixSpawnAttr
var args = ["program", "-arg1", "-arg2"]
var env = ["VAR1=value1", "VAR2=value2"]

posixSpawnFileActionsInit(actions)
# Add any necessary file actions here

posixSpawnAttrInit(attr)
# Set any necessary attributes here

let result = posixSpawnp(pid, "/path/to/program", actions, attr, args, env)
if result == 0:
  echo "Process spawned successfully with PID: ", pid
else:
  echo "Error spawning process: ", result

posixSpawnFileActionsDestroy(actions)
posixSpawnAttrDestroy(attr)
```

### Response
#### Success Response
Returns 0 on success. The PID of the spawned process is stored in the `a1` parameter. Returns an error number on failure.
```

--------------------------------

### Get Future Flags

Source: https://status-im.github.io/nim-chronos/api/chronos/futures.html

Retrieves the flags associated with a future.

```nim
func flags(future: FutureBase): FutureFlags {....raises: [], tags: [].}
```

--------------------------------

### handles: getMaxOpenFiles

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the maximum number of open files allowed.

```APIDOC
## handles: getMaxOpenFiles

### Description
Gets the maximum number of open files allowed.

### Signature
`proc getMaxOpenFiles(): int`
```

--------------------------------

### `init` (typedesc[IpMask], TransportAddress)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IP mask from a transport address.

```APIDOC
## `init` (typedesc[IpMask], TransportAddress)

### Description
Initializes an IP mask using a transport address.

### Method
`init`

### Parameters
- **t** (typedesc[IpMask]) - Type descriptor for IpMask.
- **netmask** (TransportAddress) - The transport address to use for initializing the mask.

### Response
- **IpMask** - The initialized IP mask.
```

--------------------------------

### Get Item from AsyncQueue

Source: https://status-im.github.io/nim-chronos/api/chronos/asyncsync.html

Retrieves an item from an AsyncQueue, waiting if necessary.

```APIDOC
## proc get[T](aq: AsyncQueue[T]): InternalRaisesFuture[T, (CancelledError,)]

### Description
Retrieves an item from the `AsyncQueue` `aq`, waiting if the queue is empty.

### Parameters
* `aq` (AsyncQueue[T]) - The asynchronous queue.

### Returns
The retrieved item of type T.
```

--------------------------------

### osnet: init

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Constructor for creating an InterfaceAddress object.

```APIDOC
## osnet: init

### Description
Constructor for creating an InterfaceAddress object.

### Method
Various (constructor)

### Parameters
- `ift: typedesc[InterfaceAddress], address: TransportAddress, prefix: int`
```

--------------------------------

### Get Length of AsyncQueue

Source: https://status-im.github.io/nim-chronos/api/chronos/asyncsync.html

Returns the number of elements currently in an AsyncQueue.

```nim
proc len[T](aq: AsyncQueue[T]): int {.inline, ...raises: [].}
```

--------------------------------

### Initialization Functions

Source: https://status-im.github.io/nim-chronos/api/theindex.html

This section details various initialization functions available for different components like bipbuffer, futures, raisesfutures, asyncstream, and chunkstream.

```APIDOC
## Initialization Functions

### bipbuffer.init

Initializes a BipBuffer with a specified size.

* **Parameters**:
  * `t` (typedesc[BipBuffer]) - The type descriptor for BipBuffer.
  * `size` (int) - The desired size of the buffer.
* **Returns**:
  * `BipBuffer` - The initialized BipBuffer.

### futures.init

Initializes a Future with optional flags.

* **Parameters**:
  * `F` (type Future[T]) - The type of the Future to initialize.
  * `fromProc` (static[string]) - Optional: The name of the procedure from which the Future is initialized.
  * `flags` (static[FutureFlags]) - Optional: Flags to configure the Future's behavior.
* **Returns**:
  * `Future[T]` - The initialized Future.

### raisesfutures.init

Initializes an InternalRaisesFuture with optional flags.

* **Parameters**:
  * `F` (type InternalRaisesFuture[T, E]) - The type of the InternalRaisesFuture to initialize.
  * `fromProc` (static[string]) - Optional: The name of the procedure from which the Future is initialized.
  * `flags` (static[FutureFlags]) - Optional: Flags to configure the Future's behavior.
* **Returns**:
  * `F:type` - The initialized InternalRaisesFuture.

### asyncstream.init

Initializes an AsyncStreamReader or AsyncStreamWriter with various configurations.

* **Parameters**:
  * `child` (AsyncStreamReader or AsyncStreamWriter) - The child stream.
  * `rsource` (AsyncStreamReader) - The source for reading.
  * `udata` (ref T) - User-defined data.
  * `loop` (StreamReaderLoop or StreamWriterLoop) - The event loop.
  * `bufferSize` (int) - The buffer size.
  * `vtbl` (AsyncStreamReaderVtbl or AsyncStreamWriterVtbl) - The virtual table.
  * `tsource` (StreamTransport) - The transport source.
  * `wsource` (AsyncStreamWriter) - The source for writing.
  * `queueSize` (int) - The queue size.
* **Returns**:
  * Various AsyncStream types.

### chunkstream.init

Initializes a ChunkedStreamReader or ChunkedStreamWriter.

* **Parameters**:
  * `child` (ChunkedStreamReader or ChunkedStreamWriter) - The child stream.
  * `rsource` (AsyncStreamReader) - The source for reading.
  * `bufferSize` (int) - The buffer size.
  * `udata` (ref T) - User-defined data.
  * `wsource` (AsyncStreamWriter) - The source for writing.
  * `queueSize` (int) - The queue size.
* **Returns**:
  * Various ChunkedStream types.
```

--------------------------------

### Create Generic Stream Server by Port with Callback2

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Initializes a generic stream server bound to a port, using a `StreamCallback2` for handling client connections. This overload allows for user-defined data (`udata`) to be passed to the callback.

```nim
proc createStreamServer[T](cbproc: StreamCallback2; port: Port;
                           host: Opt[IpAddress] = Opt.none(IpAddress);
                           flags: set[ServerFlags] = {}; udata: ref T;
                           sock: AsyncFD = asyncInvalidSocket;
                           backlog: int = DefaultBacklogSize;
                           bufferSize: int = DefaultStreamBufferSize;
                           child: StreamServer = nil;
                           init: TransportInitCallback = nil;
                           dualstack = DualStackType.Auto): StreamServer {. 
    ...raises: [TransportOsError], raises: [].}

```

--------------------------------

### Define ReadyKey Object for Select Results

Source: https://status-im.github.io/nim-chronos/api/chronos/selectors2.html

This object holds the file descriptor and the set of events that occurred for a ready key.

```nim
ReadyKey = object
  fd*: int                   ## file/socket descriptor
  events*: set[Event]        ## set of events
```

--------------------------------

### posixSpawnAttrGetPgroup

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Gets the process group ID from a posix_spawn attribute object.

```APIDOC
## posixSpawnAttrGetPgroup

### Description
Gets the process group ID from a posix_spawn attribute object.

### Method
posixSpawnAttrGetPgroup

### Parameters
- **a1** (var PosixSpawnAttr) - Description: The attribute object.
- **a2** (var Pid) - Description: Pointer to a Pid structure to store the retrieved process group ID.

### Returns
- (cint) - Description: 0 on success, or an error number on failure.
```

--------------------------------

### getAutoAddresses

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/common.html

Gets automatically assigned local and remote transport addresses.

```APIDOC
## getAutoAddresses

### Description
Retrieves automatically assigned local and remote transport addresses based on the provided local and remote port numbers.

### Method
`getAutoAddresses`

### Parameters
- **localPort** (Port) - The local port number.
- **remotePort** (Port) - The remote port number.

### Response
- **tuple[local: TransportAddress, remote: TransportAddress]** - A tuple containing the local and remote transport addresses.
```

--------------------------------

### Initialize BipBuffer

Source: https://status-im.github.io/nim-chronos/api/chronos/bipbuffer.html

Creates a new BipBuffer with a specified initial size.

```nim
proc init(t: typedesc[BipBuffer]; size: int): BipBuffer {"....raises: [], tags: [].}

```

--------------------------------

### getAutoAddress

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/common.html

Gets an automatically assigned transport address for a given port.

```APIDOC
## getAutoAddress

### Description
Retrieves an automatically assigned transport address for the specified port.

### Method
`getAutoAddress`

### Parameters
- **port** (Port) - The port number for which to get an address.

### Response
- **TransportAddress** - An automatically assigned transport address.
```

--------------------------------

### Get Domain from TransportAddress

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/common.html

Retrieves the OS-specific Domain from a TransportAddress object.

```nim
proc getDomain(address: TransportAddress): Domain {....raises: [], tags: [].}
```

--------------------------------

### Create Generic Stream Server with Callback (Deprecated)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Initializes a generic stream server bound to an address, using a `StreamCallback`. This overload is deprecated for callbacks that are not annotated with {.async: (raises: []).}.

```nim
proc createStreamServer[T](host: TransportAddress; cbproc: StreamCallback;
                           flags: set[ServerFlags] = {}; udata: ref T;
                           sock: AsyncFD = asyncInvalidSocket;
                           backlog: int = DefaultBacklogSize;
                           bufferSize: int = DefaultStreamBufferSize;
                           child: StreamServer = nil;
                           init: TransportInitCallback = nil;
                           dualstack = DualStackType.Auto): StreamServer {. 
    ...raises: [TransportOsError], deprecated: "Callback must not raise exceptions, annotate with {.async: (raises: []).}",
    raises: [].}

```

--------------------------------

### getSockOpt2

Source: https://status-im.github.io/nim-chronos/api/chronos/handles.html

Gets a socket option, returning a Result for error handling.

```APIDOC
## getSockOpt2 (int overload)

### Description
Gets a socket option by level and option name, returning a Result for error handling. Expects an integer value.

### Parameters
* **socket** (AsyncFD) - The asynchronous file descriptor for the socket.
* **level** (int) - The option level.
* **optname** (int) - The option name.

### Returns
A Result containing the integer option value on success, or an OSErrorCode on failure.
```

```APIDOC
## getSockOpt2 (type overload)

### Description
Gets a socket option by level and option name, returning a Result for error handling. The type `T` is inferred for the return value.

### Parameters
* **socket** (AsyncFD) - The asynchronous file descriptor for the socket.
* **level** (int) - The option level.
* **optname** (int) - The option name.
* **T** (type) - The type to which the option value should be cast.

### Returns
A Result containing the option value of type `T` on success, or an OSErrorCode on failure.
```

--------------------------------

### Define posix_spawn_file_actions_init

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Defines the Nim procedure for posix_spawn_file_actions_init, used to initialize process spawn file action structures.

```nim
proc posixSpawnFileActionsInit(a1: var PosixSpawnFileActions): cint {.importc: "posix_spawn_file_actions_init", header: "<spawn.h>", sideEffect, ...raises: [], tags: [].}
```

--------------------------------

### getMaxOpenFiles

Source: https://status-im.github.io/nim-chronos/api/chronos/handles.html

Gets the maximum number of open files allowed system-wide.

```APIDOC
## getMaxOpenFiles

### Description
Gets the maximum number of open files allowed system-wide.

### Returns
An integer representing the maximum number of open files.
```

--------------------------------

### Simple Future cancellation example

Source: https://status-im.github.io/nim-chronos/concepts.html

Demonstrates initiating cancellation for asynchronous tasks. `cancelSoon` schedules cancellation without waiting, while `cancelAndWait` ensures the Future is settled (completed, failed, or cancelled) before proceeding.

```nim
import chronos

proc someTask() {.async.} =
  await sleepAsync(10.minutes)

proc cancellationExample() {.async.} =
  # Start a task but don't wait for it to finish
  let future = someTask()

  # `cancelSoon` schedules but does not wait for the future to get cancelled -
  # it might still be pending here
  future.cancelSoon()

  let future2 = someTask() # Start another task concurrently
  await future2.cancelAndWait()
  # Using `cancelAndWait`, we can be sure that `future2` is either
  # complete, failed or be cancelled at this point. `future` could still be
  # pending!
  assert future2.finished()

waitFor cancellationExample()
```

--------------------------------

### connect

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Establishes a connection to a specified address.

```APIDOC
## connect

### Description
Establishes a connection to a specified address.

### Method
Overloaded function

### Endpoints
- stream: connect(address: TransportAddress; bufferSize = DefaultStreamBufferSize; child: StreamTransport = nil; localAddress = TransportAddress(); flags: set[SocketFlags] = {}; dualstack = DualStackType.Auto): InternalRaisesFuture[ StreamTransport, (TransportError, CancelledError)]
- stream: connect(address: TransportAddress; bufferSize = DefaultStreamBufferSize; child: StreamTransport = nil; flags: set[TransportFlags]; localAddress = TransportAddress(); dualstack = DualStackType.Auto): InternalRaisesFuture[ StreamTransport, (TransportError, CancelledError)]
```

--------------------------------

### Get Future Location Information

Source: https://status-im.github.io/nim-chronos/api/chronos/futures.html

Retrieves the location information for a future.

```nim
func location(future: FutureBase): array[LocationKind, ptr SrcLoc] {....raises: [],
    tags: [].}
```

--------------------------------

### Enable Async Dump

Source: https://status-im.github.io/nim-chronos/api/chronos/config.html

Set to true to print code generated by the {.async.} transformation. Defaults to false.

```nim
chronosDumpAsync: bool = false
```

--------------------------------

### Concurrent Await Example

Source: https://status-im.github.io/nim-chronos/async_procs.html

Demonstrates concurrent execution of two async procedures using `await`. Both futures are awaited, but only one second passes because they run concurrently, not sequentially.

```nim
proc p1() {.async.} =
  await sleepAsync(1.seconds)

proc p2() {.async.} =
  await sleepAsync(1.seconds)

proc p3() {.async.} =
  let
    fut1 = p1()
    fut2 = p2()
  # Just by executing the async procs, both resulting futures entered the
  # dispatcher queue and their "clocks" started ticking.
  await fut1
  await fut2
  # Only one second passed while awaiting them both, not two.

waitFor p3()
```

--------------------------------

### asyncsync: getNoWait

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Attempts to get an item from an async queue without blocking.

```APIDOC
## asyncsync: getNoWait

### Description
Attempts to get an item from an async queue without blocking.

### Signature
`proc getNoWait[T](aq: AsyncQueue[T]): T`
```

--------------------------------

### common: getDomain

Source: https://status-im.github.io/nim-chronos/api/theindex.html

Gets the address family domain of a socket or transport address.

```APIDOC
## common: getDomain

### Description
Gets the address family domain of a socket or transport address.

### Signature
`proc getDomain(socket: AsyncFD): Result[AddressFamily, OSErrorCode]`
`proc getDomain(address: TransportAddress): Domain`
```

--------------------------------

### Initialize InternalRaisesFuture (with Flags)

Source: https://status-im.github.io/nim-chronos/api/chronos/internal/raisesfutures.html

A template to create a new pending `InternalRaisesFuture`, allowing for additional `FutureFlags` to be specified. It is recommended to specify `fromProc` for debugging purposes.

```nim
template init[T, E](F: type InternalRaisesFuture[T, E];
                    fromProc: static[string] = ""; flags: static[FutureFlags]): F:type
```

--------------------------------

### Get Subnet Mask as TransportAddress

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Returns the TransportAddress representation of an IP mask.

```nim
proc subnetMask(mask: IpMask): TransportAddress {....raises: [], tags: [].}
```

--------------------------------

### Initialize IpNet from Host and Mask Addresses

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/ipnet.html

Initializes an IpNet using a host address and a network mask address. Both must be from the same IP family.

```nim
proc init(t: typedesc[IpNet]; host, mask: TransportAddress): IpNet {.inline, ...raises: [].}
```

--------------------------------

### remoteAddress2

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/datagram.html

Gets the remote address of the datagram transport, returning a Result type.

```APIDOC
## remoteAddress2

### Description
Returns the remote transport address associated with the datagram transport, with error handling.

### Signature
`remoteAddress2(transp: DatagramTransport): Result[TransportAddress, OSErrorCode]`

### Parameters
* `transp` (DatagramTransport) - The datagram transport instance.

### Returns
* `Result[TransportAddress, OSErrorCode]` - A result containing the remote address or an OSErrorCode on failure.
```

--------------------------------

### localAddress2

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/datagram.html

Gets the local address of the datagram transport, returning a Result type.

```APIDOC
## localAddress2 DatagramTransport

### Description
Gets the local address of the datagram transport, returning a Result type.

### Method
(Implicitly a procedure call, not HTTP)

### Parameters
* **transp** (DatagramTransport) - The datagram transport.

### Returns
* Result[TransportAddress, OSErrorCode] - A Result containing the transport address or an OSErrorCode.
```

--------------------------------

### Define posix_spawn_file_actions_addopen

Source: https://status-im.github.io/nim-chronos/api/chronos/osdefs.html

Defines the Nim procedure for posix_spawn_file_actions_addopen, used for opening files as part of process spawning.

```nim
proc posixSpawnFileActionsAddOpen(a1: var PosixSpawnFileActions; a2: cint; a3: cstring; a4: cint; a5: Mode): cint {.importc: "posix_spawn_file_actions_addopen", header: "<spawn.h>", sideEffect, ...raises: [], tags: [].}
```

--------------------------------

### Creating a Stream Server (IPv6/IPv4 Binding)

Source: https://status-im.github.io/nim-chronos/api/chronos/transports/stream.html

Creates a stream server that binds to IPv6 or IPv4 addresses. Supports custom callbacks, ports, hosts, flags, sockets, backlog, buffer sizes, child servers, initialization, and user data. Can raise TransportOsError.

```nim
proc createStreamServer(cbproc: StreamCallback2; port: Port; host: Opt[IpAddress] = Opt.none(IpAddress); flags: set[ServerFlags] = {}; sock: AsyncFD = asyncInvalidSocket; backlog: int = DefaultBacklogSize; bufferSize: int = DefaultStreamBufferSize; child: StreamServer = nil; init: TransportInitCallback = nil; udata: pointer = nil; dualstack = DualStackType.Auto): StreamServer {. ...raises: [TransportOsError], raises: [], tags: [RootEffect].}
```

--------------------------------

### Get Item from AsyncQueue

Source: https://status-im.github.io/nim-chronos/api/chronos/asyncsync.html

Retrieves an item from the AsyncQueue. Blocks if the queue is empty.

```nim
proc get[T](aq: AsyncQueue[T]): InternalRaisesFuture[T, (CancelledError,)] {
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [].}
```
Tokens:
Raw