diff --git a/async_context/main/.doctrees/api/async_context.doctree b/async_context/main/.doctrees/api/async_context.doctree index 59a6392..8414be6 100644 Binary files a/async_context/main/.doctrees/api/async_context.doctree and b/async_context/main/.doctrees/api/async_context.doctree differ diff --git a/async_context/main/.doctrees/environment.pickle b/async_context/main/.doctrees/environment.pickle index f1f64c9..620a56b 100644 Binary files a/async_context/main/.doctrees/environment.pickle and b/async_context/main/.doctrees/environment.pickle differ diff --git a/async_context/main/_sources/api/async_context.md.txt b/async_context/main/_sources/api/async_context.md.txt index cea1a59..5d2c317 100644 --- a/async_context/main/_sources/api/async_context.md.txt +++ b/async_context/main/_sources/api/async_context.md.txt @@ -9,7 +9,7 @@ Defined in namespace `async::v0` ```{doxygenclass} v0::context ``` -## async::basic_context +## async::inplace_context Defined in namespace `async::v0` diff --git a/async_context/main/api/async_context.html b/async_context/main/api/async_context.html index 4fc49c6..0fdec31 100644 --- a/async_context/main/api/async_context.html +++ b/async_context/main/api/async_context.html @@ -418,14 +418,25 @@

async::contextNote

Context objects should be kept alive as long as coroutines are running on them. The context must be properly cleaned up to prevent memory leaks.

-

Subclassed by v0::basic_context_impl, v0::proxy_context

+

Subclassed by v0::inplace_context< StackSizeInWords >, v0::proxy_context

Public Functions

context() = default#

Default constructor for context.

-

Creates an uninitialized context. Derived classes must call initialize_stack_memory() to properly set up the stack memory.

+

Creates context without a stack. initialize_stack_memory() must be called before passing this context to a coroutine.

+
+ +
+
+inline context(std::span<uptr> p_stack)#
+

Construct a new context object with stack memory.

+
+
Parameters:
+

p_stack – - the stack memory for the async operations

+
+
@@ -444,16 +455,29 @@

async::context
-context(context&&) = delete#
-

Delete move constructor.

-

Contexts cannot be moved as they manage unique stack memory.

+inline context(context &&p_other) noexcept#
+

Move constructor.

+

Transfers ownership of stack and state from the source context. The moved-from context is reset to its default state (no stack, no active operations).

+
+
Parameters:
+

p_other – The context to move from (will be reset to default state)

+
+

-context &operator=(context&&) = delete#
-

Delete move assignment operator.

-

Contexts cannot be moved as they manage unique stack memory.

+inline context &operator=(context &&p_other) noexcept#
+

Move assignment operator.

+

Transfers ownership of stack and state from the source context. The current context is cancelled before assignment, and the moved-from context is reset to its default state.

+
+
Parameters:
+

p_other – The context to move from (will be reset to default state)

+
+
Returns:
+

Reference to this context

+
+
@@ -473,30 +497,33 @@

async::context

-
-inline constexpr void unblock() noexcept#
-

Unblocks a coroutine that was previously blocked.

-

This method transitions the context from any blocking state to “nothing” (ready to run) state. It’s typically called by I/O completion handlers or when external conditions that were blocking a coroutine have been resolved.

-
-

Note

-

This method is noexcept and should not throw exceptions. It’s used internally by I/O completion handlers to signal that a blocked coroutine can now proceed.

-
+
+inline constexpr void unblock_without_notification() noexcept#
+

Unblocks the context without invoking the unblock listener.

+

This method transitions the context to “nothing” (ready to run).

-
-inline constexpr void unblock_without_notification() noexcept#
-

Unblocks a coroutine without notifying the scheduler.

-

This method transitions the context to “nothing” (ready to run) state but does not call the scheduler’s do_schedule method. This is useful in cases where the scheduler state is being managed externally or during cleanup.

+
+inline constexpr void unblock() noexcept#
+

Unblocks the context and clears blocking state.

+

The state of the context after this is called:

+

    +
  1. Block state becomes (block_by::nothing)

  2. +
  3. sleep time is set to 0us.

  4. +
  5. sync blocker is set to nullptr.

  6. +
+

+

The unblock listener is called before clearing the context state in the event that the unblock listener wants to inspect information from the context.

Note

-

This method is noexcept and should not throw exceptions.

+

this API is safe to call within an interrupt service routine.

-
-inline constexpr std::suspend_always block_by_time(sleep_duration p_duration) noexcept#
+
+template<typename Rep, typename Period>
inline constexpr std::suspend_always block_by_time(std::chrono::duration<Rep, Period> p_duration) noexcept#

Blocks the context for a specified time duration.

This method blocks the current coroutine for the specified duration, transitioning it to the time-blocking state. The scheduler is responsible for resuming this context after the duration has elapsed.

@@ -577,8 +604,8 @@

async::context

-
-inline constexpr bool done()#
+
+inline constexpr bool done() const#

Check if the context has completed its operation.

This method determines whether the context is in a “done” state, meaning it has completed all operations and no longer needs to be scheduled. The stack memory of the context should be completely unused when this function returns true.

@@ -607,6 +634,25 @@

async::contextThis method resumes the currently active coroutine. It only has an effect if the context is not blocked by time, as time-blocking contexts must wait for their designated duration to elapse.

+
+
+inline void sync_wait(std::invocable<sleep_duration> auto &&p_delay)#
+

Perform sync_wait operation.

+

This method waits synchronously for all coroutines on this context to complete. It uses the provided delay function to sleep for the required duration when waiting for time-based operations.

+
+

Note

+

This method is primarily intended for testing and simple applications where a synchronous wait is needed. It’s not suitable for production embedded systems that require precise timing or real-time scheduling.

+
+
+
Template Parameters:
+

DelayFunc – The type of the delay function (must be invocable with sleep_duration parameter)

+
+
Parameters:
+

p_delay – - a delay function, that accepts a sleep duration and returns void.

+
+
+
+
inline constexpr auto memory_used() const noexcept#
@@ -644,33 +690,64 @@

async::context

-
-virtual ~context() = default#
-

Virtual destructor for proper cleanup of derived classes.

-

This virtual destructor ensures that derived context classes are properly cleaned up when deleted through a base class pointer.

+
+inline constexpr sleep_duration sleep_time() const noexcept#
+

Amount of time to delay resuming this context.

+

When a context is blocked by for a set duration of time, it is the responsibility of the scheduler to ensure that the context is not resumed until that duration of time has elapsed. In the event that the context is not blocked by time, then this returns 0.

+

Calling this function multiple times returns the last sleep duration that was set by the async operation contained within the context. It is the responsibility of the scheduler to unblock this context, otherwise, calling resume() will immediately without resuming async operation.

+
+
Returns:
+

constexpr sleep_duration - the amount of time to delay resuming this context.

+
+
-
+
+
+inline void on_unblock(unblock_listener *p_listener)#
+

Sets the unblock listener.

+

There can only be a single unblock listener per context, thus any previously set unblock listener will be removed.

+

Because this API takes the address of the listener, it is important that the context outlive the listener.

+

remove_unblock_handler() must be called before the end of the lifetime of the p_listener object. It is undefined behavior to allow a listener to be destroyed before it is removed from this context.

+
+
Parameters:
+

p_listener – - the address of the unblock listener to be invoked when this context is unblocked.

+
+
- -
-

async::basic_context#

-

Defined in namespace async::v0

-

import async_context;

-
-
-template<size_t StackSizeInWords>
class basic_context#
-

A basic context implementation that supports synchronous waiting.

-

The basic_context class provides a concrete implementation of the context interface that supports synchronous waiting operations. It extends the base context with functionality to wait for coroutines to complete using a simple synchronous loop.

-

This class provides stack memory via its StackSizeInWords template variable.

+
+
+inline void clear_unblock_listener() noexcept#
+

Clears the on_unblock listener from this context.

+

After this is called, any call to unblock() will not invoke an unblock listener.

+

It is the responsibility of the application to clear the unblock listener is cleared, before the end of the lifetime of the object that was passed to on_unblock().

+
+ +
+
+inline context const *get_blocker() const#
+

Get the address of the context currently blocking this one blocking.

+

If this context’s state is blocked_by::sync then there is a context that currently holds a resource that this context needs. That context’s address can be acquired by this API.

-
Template Parameters:
-

StackSizeInWords – - the number of words to allocate for the context’s stack memory. Word size is 4 bytes for 32-bit systems and 8 bytes on 64-bit systems.

+
Returns:
+

context const* - returns a const pointer to the other context that is blocking this context. If no such context exists, then a nullptr is returned.

+ +
+ +
+
+

async::inplace_context#

+

Defined in namespace async::v0

+

import async_context;

+
+

Warning

+

doxygenclass: Cannot find class “v0::basic_context” in doxygen xml output for project “async_context” from directory: build/xml

+

async::proxy_context#

@@ -714,7 +791,7 @@

async::proxy_context
-inline ~proxy_context() override#
+inline ~proxy_context()#

Destructor for proxy_context.

The destructor cancels any remaining operations and properly restores the parent context’s stack memory to its original state.

@@ -1190,34 +1267,36 @@

async::future<T>async::context -
  • async::basic_context
  • +
  • async::inplace_context
  • async::proxy_context