# Nuclei

> Proactive async runtime for Rust. A task hands its IO to the driver and gets the result back completed, one shard per core, on io_uring, epoll, kqueue and I/O completion ports.

Nuclei 0.5.3 needs Rust 1.99 or newer. Add it to Cargo.toml:

```toml
[dependencies]
nuclei = "0.5.3"
```

These files are built from commit 522f3a61affd58eb53d8a4d5a9505eff201b07a7 of github.com/vertexclique/nuclei with the site, on every push to master, so they describe the code as it is there. The Learn chapters teach the crate from the first program to production, with a program that compiles and runs for every idea; the API reference holds every public item.

## Learn

- [Learn Nuclei](https://nuclei.rs/learn/index.md): Where to start, and the chapters in order.
- [Setup](https://nuclei.rs/learn/setup.md): Add Nuclei, run a first program, pick features, see which backend runs.
- [How it works](https://nuclei.rs/learn/proactive.md): Shards, the proactor and its buffers: the few ideas the rest builds on.
- [Runtime](https://nuclei.rs/learn/runtime.md): Enter the runtime: the attribute, block_on, a runtime of your own and its workers.
- [Tasks](https://nuclei.rs/learn/tasks.md): Spawn, join, cancel and name tasks; local, blocking and task-local work.
- [Select and join](https://nuclei.rs/learn/select.md): Wait on several futures in one task: join!, try_join! and select!.
- [Networking](https://nuclei.rs/learn/net.md): TCP, UDP and Unix sockets, names, socket options, halves, ending a stream and pipes.
- [IO utilities](https://nuclei.rs/learn/io.md): Read and write helpers, copies, buffers you lend, in-memory pipes and the standard streams.
- [Readiness](https://nuclei.rs/learn/readiness.md): Readiness waits, the try_ calls, and system calls of your own.
- [Files](https://nuclei.rs/learn/fs.md): Files, IO at an offset and direct IO, syncs, locks, metadata and directories.
- [Time](https://nuclei.rs/learn/time.md): Sleeps to the millisecond or the microsecond, timeouts, intervals, and a clock tests can stop.
- [Sync](https://nuclei.rs/learn/sync.md): Locks, semaphores, notifications, once-cells, lock-free structures and their one-shard twins.
- [Channels](https://nuclei.rs/learn/channels.md): mpsc, oneshot, broadcast and watch channels, meshes between workers, and cancellation tokens.
- [Processes](https://nuclei.rs/learn/processes.md): Child processes with async pipes, and signals as streams.
- [Production](https://nuclei.rs/learn/production.md): Every runtime setting, hooks, counters, shutdown, tests and allocation.
- [Backends](https://nuclei.rs/learn/backends.md): io_uring, epoll, kqueue and IOCP: how one is picked and what differs.
- [Errors](https://nuclei.rs/learn/errors.md): The messages you may meet, what each means, and the fix.
- [Migrate](https://nuclei.rs/learn/migrate.md): Coming from a readiness-based runtime: the map and the pitfalls.

## API

- [API reference](https://nuclei.rs/api.md): every public item and member, with its signature and documentation
- [rustdoc](https://nuclei.rs/api/nuclei/): the same reference as HTML

## Optional

- [Everything in one file](https://nuclei.rs/llms-full.txt): the Learn chapters, the API reference and the changelog
- [Changelog](https://raw.githubusercontent.com/vertexclique/nuclei/master/CHANGELOG.md): what changed in each release, and how to move from 0.4