# Runtime
A FutureSDR [Runtime](https://docs.rs/futuresdr/latest/futuresdr/runtime/struct.Runtime.html) owns a [Scheduler](scheduler.md) and starts one or more [Flowgraphs](flowgraph.md). On native targets, the runtime can start an integrated web server to serve a web UI and expose the [control port](remote_interaction.md#rest-api) interface for runtime and flowgraph interaction.
## Running a Flowgraph
The simplest way to execute a flowgraph is to construct a runtime, pass the flowgraph to `run()`, and block until it terminates.
```rust
let mut fg = Flowgraph::new();
// set up the flowgraph
let fg = Runtime::new().run(fg)?;
```
The `run()` method is a blocking call that takes ownership of the flowgraph and returns the finished flowgraph after all blocks have terminated. This is useful when you need to inspect blocks after execution, for example to read data or statistics.
In async code, use `run_async()` instead:
```rust
let mut fg = Flowgraph::new();
// set up the flowgraph
let fg = Runtime::new().run_async(fg).await?;
```
## Starting a Flowgraph
Use `start_async()` when the application should keep doing other work while the flowgraph is running. It returns once all blocks have initialized.
```rust
let mut fg = Flowgraph::new();
// set up the flowgraph
let rt = Runtime::new();
let running = rt.start_async(fg).await?;
```
On native targets, `start()` provides the same behavior from synchronous code:
```rust
let mut fg = Flowgraph::new();
// set up the flowgraph
let rt = Runtime::new();
let running = rt.start(fg)?;
```
Both methods return a [`RunningFlowgraph`](https://docs.rs/futuresdr/latest/futuresdr/runtime/struct.RunningFlowgraph.html). It combines the completion task with a [`FlowgraphHandle`](https://docs.rs/futuresdr/latest/futuresdr/runtime/struct.FlowgraphHandle.html):
```rust
let running = rt.start(fg)?;
let handle = running.handle();
Runtime::block_on(async move { handle.post(block_id, "handler_name", Pmt::U32(42)).await })?;
let fg = running.wait()?;
```
Use `running.post()` and `running.call()` to interact with blocks, `running.wait()` to block until termination on native targets, and `running.wait_async().await` in async code. `running.stop_and_wait().await` requests shutdown and then recovers the finished flowgraph. Use `running.handle()` when you need to keep a clonable control handle. If you need to pass the two parts around separately, `running.split()` returns the `FlowgraphTask` and `FlowgraphHandle`.
## Selecting a Scheduler
To use a different scheduler or change its configuration, you can specify it when constructing the runtime.
```rust
let mut fg = Flowgraph::new();
// set up the flowgraph
let rt = Runtime::with_scheduler(FlowScheduler::new());
rt.run(fg)?;
```
## Runtime Handle
A [RuntimeHandle](https://docs.rs/futuresdr/latest/futuresdr/runtime/struct.RuntimeHandle.html) is a clonable control handle for the runtime. It is useful when other tasks, threads, web handlers, or callbacks need to start flowgraphs or query the flowgraphs registered with the runtime control plane.
```rust
let rt = Runtime::new();
let runtime_handle = rt.handle();
Runtime::block_on(async move {
let mut fg = Flowgraph::new();
// set up the flowgraph
let running = runtime_handle.start(fg).await?;
let flowgraph_handle = running.handle();
let description = flowgraph_handle.describe().await?;
Ok::<_, futuresdr::runtime::Error>(())
})?;
```
`RuntimeHandle::start()` returns a `RunningFlowgraph`. It also registers the flowgraph with the runtime control plane, so it remains available through `get_flowgraph()` and the control port.
## Initialization and Logging
Constructing a runtime calls `futuresdr::runtime::init()` automatically. At the moment, initialization installs FutureSDR's default tracing subscriber when no subscriber is already installed. Call it manually only when application code wants to emit FutureSDR logs before constructing the runtime:
```rust
use futuresdr::prelude::*;
fn main() -> Result<()> {
futuresdr::runtime::init();
info!("parsing configuration before the runtime exists");
let rt = Runtime::new();
// build and run flowgraphs
Ok(())
}
```
If an application installs its own `tracing` subscriber first, FutureSDR leaves it in place. See [Logging](logging.md) for runtime and compile-time filtering details.