drone-core

If you need to enable or extend the host feature for drone-core, configure your [features] section in Cargo.toml to include drone-core/host.

[features]
host = ["drone-core/host"]

To use drone-core in your project, add it to your Cargo.toml dependencies. Note that while the current repository version is v0.14.3, the documentation example uses v0.15.0.

[dependencies]
drone-core = { version = "0.15.0" }

The LinkedList<T> is a singly-linked list where each element is wrapped in a Node<T>.

• LinkedList<T>: Manages the head pointer using atomic operations to ensure thread safety (lock-free). It handles the high-level logic of pushing, popping, and iterating.
• Node<T>: A #[repr(C)] structure containing the actual value: T and a raw pointer next to the subsequent node.

When using high-level methods like push(data), the list automatically allocates a Node on the heap using Box. When using pop(), the list takes ownership of the node, extracts the value, and deallocates the node memory automatically.

The communication between the asynchronous session and the synchronous fiber is mediated by In and Out types.

Fiber Input (In<Cmd, ReqRes>)

A union representing what is sent into the fiber. It can be either:

• cmd: A command to be executed by the ProcLoop.
• req_res: The result of a previously made request.

Fiber Output (Out<Req, CmdRes>)

An enum representing what the fiber yields back to the session:

• Req(Req): The fiber is requesting a resource or action, suspending itself until the request is answered.
• CmdRes(CmdRes): The fiber has completed the current command and is returning the result.

When you acquire a lock via lock() or try_lock(), you receive a MutexGuard. This guard implements Deref and DerefMut, allowing you to access the underlying data directly. The lock is automatically released when the guard is dropped (RAII).

Warning: If you do not use the returned guard, the mutex will be immediately unlocked.

The CfgCond struct is used to represent and generate conditional compilation attributes (#[cfg(...)]) based on feature-based configurations. It supports representing logical combinations of clauses, specifically handling any conditions and generating the appropriate Rust TokenStream for attributes.

Key behaviors:

• It can represent a set of clauses in Conjunctive Normal Form (CNF).
• It can generate #[cfg(any(...))] or #[cfg(not(any(...)))] attributes via the .attrs() method.
• It provides a mechanism to add clauses to an existing condition using .add_clause().

Fiber stream rings allow a fiber running in one thread to yield data to a stream that can be consumed in another thread. This is achieved by attaching a fiber to a ThrToken (like a thread token) and using ring buffer methods to bridge the data flow.

There are two primary overflow behaviors when the underlying ring buffer is full:

1. Saturating: New items are skipped if the buffer is full.
2. Overwriting: New items overwrite existing items in the buffer.

Additionally, you can choose between:

• Standard Streams: Yielding T directly via FiberStreamRing<T>.
• Try Streams: Yielding Result<T, E> via TryFiberStreamRing<T, E>, which allows the fiber to signal errors.
• Factory Methods: If your fiber is !Send, use the _factory variants which take a closure to instantiate the fiber within the target thread.

If you are developing for a host environment (rather than an embedded target), you can add or extend the host feature in your Cargo.toml.

[features]
host = ["drone-core/host"]

Streams are not necessarily active by default. To avoid unnecessary processing, check if a stream is explicitly enabled by a debug probe using is_enabled(). It is highly recommended to wrap write operations in this check.

use drone_core::stream;

let stream_id = 11;
if stream::Stream::new(stream_id).is_enabled() {
    stream::write_str(stream_id, "hello there!\n");
}

use drone_core::stream;

if stream::Stream::new(11).is_enabled() {
    stream::write_str(11, "hello there!\n");
}

To use drone-core in your project, add it to your Cargo.toml dependencies. Note that the current version in this file is 0.15.0.

[dependencies]
drone-core = { version = "0.15.0" }