diff --git a/examples/BUILD b/examples/BUILD new file mode 100644 index 0000000..2c87b2b --- /dev/null +++ b/examples/BUILD @@ -0,0 +1,31 @@ +# ******************************************************************************* +# Copyright (c) 2025 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +alias( + name = "select", + actual = "//src/kyron:select", +) + +alias( + name = "main_macro", + actual = "//src/kyron:main_macro", +) + +alias( + name = "mpmc", + actual = "//src/kyron:mpmc", +) + +alias( + name = "safety_task", + actual = "//src/kyron:safety_task", +) diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..757a667 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,98 @@ +# Kyron Examples + +Kyron examples are located in [examples](../src/kyron/examples) directory due to the fact +that Kyron is published to `crates.io` and official project structure needs to be followed. +In this directory there are Bazel aliases located for compatybility. + +## Running Examples + +All examples can be run using Bazel: + +```bash +bazel run //examples:select +bazel run //examples:main_macro +bazel run //examples:mpmc +bazel run //examples:safety_task +``` + +## Available Examples + +### select.rs + +Demonstrates the `select!` macro for waiting on multiple async tasks and handling whichever completes first. This example shows: + +- Using `select!` to race multiple spawned tasks +- Pattern matching on different future results +- Handling both success (`Ok`) and error (`Err`) cases in select branches +- Working with the safety worker + +**Key concepts:** `select!` macro, concurrent task racing, pattern matching futures + +### main_macro.rs + +A simple example showing how to use the `#[kyron::main]` macro to quickly set up an async runtime with default parameters. + +- Spawning multiple async tasks in a loop +- Using the main macro for simplified runtime initialization +- Waiting on task handles with `await` + +**Key concepts:** `#[kyron::main]` macro, task spawning, async/await + +### mpmc.rs + +Demonstrates the work-stealing behavior of Kyron's task scheduler with a Multi-Producer Multi-Consumer (MPMC) queue pattern. + +This example illustrates: + +- How tasks are distributed between local and global queues +- Work-stealing mechanics when the local queue overflows +- Queue size limits and worker behavior (1 worker with queue size of 8) +- The order in which tasks are executed based on queue management + +**Key concepts:** Work stealing, task queue management, worker scheduling + +### safety_task.rs + +Shows how to use Kyron's safety-critical features, including: + +- Spawning safety-critical tasks with `safety::spawn()` +- Using dedicated workers with `spawn_on_dedicated()` +- Handling task failures in safety-critical contexts +- Configuring the safety worker via `RuntimeBuilder` +- Task context introspection (`TaskContext::worker_id()`, `TaskContext::task_id()`) + +**Key concepts:** Safety-critical tasks, dedicated workers, task context, failure handling + +## Runtime Configuration + +Most examples demonstrate different runtime configurations: + +- **Workers:** Number of worker threads for task execution +- **Task queue size:** Size of the per-worker task queue +- **Dedicated workers:** Named workers for specific tasks +- **Safety worker:** Special worker for safety-critical tasks +- **Thread parameters:** Configuration for worker threads + +Example runtime setup: + +```rust +let (builder, _engine_id) = kyron::runtime::RuntimeBuilder::new().with_engine( + ExecutionEngineBuilder::new() + .task_queue_size(256) + .workers(3) + .with_dedicated_worker("dedicated".into(), ThreadParameters::default()) + .enable_safety_worker(ThreadParameters::default()), +); +let mut runtime = builder.build().unwrap(); +``` + +## Logging + +All examples use `tracing_subscriber` for structured logging. The log output shows: + +- Thread IDs and names +- Task execution flow +- Worker assignment +- Runtime events + +Adjust the log level by modifying `with_max_level()` in the example code (e.g., `Level::DEBUG`, `Level::INFO`, `Level::TRACE`). diff --git a/src/kyron/BUILD b/src/kyron/BUILD index e745648..f1d6d8c 100644 --- a/src/kyron/BUILD +++ b/src/kyron/BUILD @@ -77,6 +77,7 @@ rust_test( ] + _COMMON_DEPS, ) +# Examples binaries rust_binary( name = "select", srcs = [ @@ -100,3 +101,27 @@ rust_binary( visibility = ["//visibility:public"], deps = _EXAMPLE_DEPS, ) + +rust_binary( + name = "mpmc", + srcs = [ + "examples/mpmc.rs", + ], + proc_macro_deps = [ + "//src/kyron-macros:runtime_macros", + ], + visibility = ["//visibility:public"], + deps = _EXAMPLE_DEPS, +) + +rust_binary( + name = "safety_task", + srcs = [ + "examples/safety_task.rs", + ], + proc_macro_deps = [ + "//src/kyron-macros:runtime_macros", + ], + visibility = ["//visibility:public"], + deps = _EXAMPLE_DEPS, +) diff --git a/src/kyron/examples/playground.rs b/src/kyron/examples/playground.rs index a9a0711..731e52c 100644 --- a/src/kyron/examples/playground.rs +++ b/src/kyron/examples/playground.rs @@ -103,6 +103,4 @@ fn main() { 0 }); - - println!("sdfdsf"); }