Crate nuclei

Nuclei

Nuclei is a proactive IO system which is runtime agnostic and can work with any runtime. Proactive system’s design principles matching to Boost Asio. Nuclei is not using conventional reactor approach. It is completely asynchronous, and it’s wrapping poll based IO proactive fashion.

Nuclei uses epoll on Linux as primary evented IO backend, secondarily (if your system supports) you can use io_uring. On MacOS, Nuclei is using kqueue. On Windows, IOCP backend is used.

Current io_uring implementation needs Linux kernel 5.6+.

Features

• Async TCP, UDP, Unix domain sockets and files…
• Proactor system don’t block.
• Scatter/Gather operations
• Minimal allocation as much as possible.
• More expressive than any other runtime.
• Completely asynchronous I/O system with lock free programming.

Examples

For more information about how to use Nuclei with std IO types please head to examples.

Executor

Executor is using async-global-executor. Available features are:

• async-exec: Uses async-io feature of async-global-executor.
• tokio: Uses tokio

Modules

• config
  Nuclei’s configuration options reside here.

Structs

• GlobalExecutorConfig
  Configuration to init the thread pool for the multi-threaded global executor.
• Handle
  Handle that manages IO submitted to proactor system.
• Proactor
  Concrete proactor instance
• Task
  A spawned task.

Traits

• HandleOpRegisterer
  Operation registrar for Proactive IO, represents the outer ring that will send & receive submissions and completions respectively.

Functions

• block_on
  Runs the global and the local executor on the current thread
• drive
  IO driver that drives underlying event systems
• init
  Init the global executor, spawning as many threads as the number or cpus or the value specified by the ASYNC_GLOBAL_EXECUTOR_THREADS environment variable if specified.
• init_with_config
  Init the global executor, spawning as many threads as specified or the value specified by the specified environment variable.
• spawn
  Spawns a task onto the multi-threaded global executor.
• spawn_blocking
  Runs blocking code on a thread pool.
• spawn_local
  Spawns a task onto the local executor.
• spawn_more_threads
  Spawn more executor threads, up to configured max value.
• stop_current_thread
  Stop the current executor thread, if we exceed the configured min value
• stop_thread
  Stop one of the executor threads, down to configured min value

Type Aliases

• AsyncOp
  Submitted async IO operation type

Attribute Macros

• bench
  Enables an async benchmark function.
• main
  Enables an async main function.
• test
  Enables an async test function.