co_usb::ev::detail::handler_service Struct Reference

Execution context service that owns a libusb context and an event handler. More...

#include <handler_service.hpp>

Inheritance diagram for co_usb::ev::detail::handler_service:

Collaboration diagram for co_usb::ev::detail::handler_service:

Public Member Functions
	handler_service (boost::capy::execution_context &exec_ctx)
	Construct the handler service.
	~handler_service () override
	Destructor that stops the handler and releases the libusb context.
auto	init_context () noexcept -> std::error_code
	Initializes libusb context without options.
auto	init_context (std::span< const libusb_init_option > options) noexcept -> std::error_code
	Initializes libusb context with given options.
template<detail::EventHandler HandlerTy, typename... Args> requires (!std::same_as<HandlerTy, any_event_handler> && !std::same_as<HandlerTy, event_handler_ref> && std::constructible_from<HandlerTy, Args...>)
auto	emplace_handler (Args &&...args, std::pmr::memory_resource *memres=std::pmr::get_default_resource()) -> event_handler_ref
	Emplace a concrete event handler and return a reference wrapper.
auto	get_token () const noexcept -> std::stop_token
	Get the stop token used for coordinating shutdown.
auto	request_stop ()
	Request stop for the event handler.
auto	handler () -> event_handler_ref
	Get a reference to the stored event handler.
auto	start () -> bool
	Start the stored event handler.
auto	shutdown () -> void override
	Shutdown hook invoked by the base service.
auto	usb_context () -> libusb_context *
	Access the underlying libusb context.

Friends
struct	co_usb::context

Detailed Description

Execution context service that owns a libusb context and an event handler.

A service to run an co_usb::ev::details::EventHandler responsible for storing libusb context, the handler itself and the stop source for the service.

Why not an executor?

An executor at its essence is a driver for executing ready coroutines. A libusb event handler is just about handling libusb-specific events not necesserily bound to a coroutine. Making the event handler logic bound to a specific library-provided executor would lock the executor choice on a single one which may not be the most effecient one. A separate service on the other hand provides flexibility in executor choice and does not limit the user in the choice of a specific handler.

Creating the service

Unlike in usb_asio library, the service will not be automatically created with the creation of any object that may require it. This is because co_usb does not have a default event handler, on purpose. Choice of a handler is fully placed on the user of the library via co_usb::ev::context and co_usb::make_context.

int main (int argc, char **argv)
{
    // pick any executor
    boost::capy::thread_pool;
    // this creates handler service with handler_type event handler
    co_usb::ev::context usb_ctx = co_usb::make_context<handler_type>(...);
}

Attempts to use any of co_usb features that require a handler or a context will result in immedeate std::runtime_error exception.

Switching the event handler

Switching the handler is allowed via emplace_handler method and is well-defined. Doing so will request stop for the currently active handler and block until it is stopped. The stop source will be reset and the new handler will not start until start is called again.

Constructor & Destructor Documentation

handler_service()

co_usb::ev::detail::handler_service::handler_service ( boost::capy::execution_context &  exec_ctx )

inlineexplicit

Construct the handler service.

Parameters

exec_ctx

Execution context to attach the service to.

~handler_service()

co_usb::ev::detail::handler_service::~handler_service ( )

inlineoverride

Destructor that stops the handler and releases the libusb context.

Calls shutdown() and then libusb_exit(m_usb_ctx).

Member Function Documentation

emplace_handler()

template<detail::EventHandler HandlerTy, typename... Args>
requires (!std::same_as<HandlerTy, any_event_handler> && !std::same_as<HandlerTy, event_handler_ref> && std::constructible_from<HandlerTy, Args...>)

auto co_usb::ev::detail::handler_service::emplace_handler ( Args &&...  args, std::pmr::memory_resource *  memres = std::pmr::get_default_resource()  ) -> event_handler_ref

inline

Emplace a concrete event handler and return a reference wrapper.

This requires HandlerTy to satisfy detail::EventHandler and be neither any_event_handler nor event_handler_ref.

Side effects

Calling this while a handler is already running will request stop for the currently active handler and block until it is stopped. The stop source will be reset and the new handler will not start until start is called again.

Template Parameters

HandlerTy	Concrete event handler type.
Args	Constructor argument types for HandlerTy.

Parameters

args	Constructor arguments for the event handler.
memres	Memory resource used by the internal handler storage.

Returns

event_handler_ref referencing the stored handler.

get_token()

auto co_usb::ev::detail::handler_service::get_token ( ) const -> std::stop_token

inlinenoexcept

Get the stop token used for coordinating shutdown.

Returns

std::stop_token associated with the internal std::stop_source.

handler()

auto co_usb::ev::detail::handler_service::handler ( ) -> event_handler_ref

inline

Get a reference to the stored event handler.

Returns

event_handler_ref for the handler owned by this service.

init_context() [1/2]

auto co_usb::ev::detail::handler_service::init_context ( ) -> std::error_code

inlinenoexcept

Initializes libusb context without options.

Returns

std::error_code result of the init operation

init_context() [2/2]

auto co_usb::ev::detail::handler_service::init_context ( std::span< const libusb_init_option >  options ) -> std::error_code

inlinenoexcept

Initializes libusb context with given options.

Returns

std::error_code result of the init operation

request_stop()

auto co_usb::ev::detail::handler_service::request_stop ( )

inline

Request stop for the event handler.

Interrupts libusb's event handling using libusb_interrupt_event_handler and then requests stop on the internal std::stop_source.

shutdown()

auto co_usb::ev::detail::handler_service::shutdown ( ) -> void

inlineoverride

Shutdown hook invoked by the base service.

Requests stop and waits for handler shutdown via m_handler.stop().

start()

auto co_usb::ev::detail::handler_service::start ( ) -> bool

inline

Start the stored event handler.

Returns

true on successful start.

usb_context()

auto co_usb::ev::detail::handler_service::usb_context ( ) -> libusb_context *

inline

Access the underlying libusb context.

Returns

Pointer to libusb_context.

Friends And Related Symbol Documentation

co_usb::context

friend struct co_usb::context

friend

---

The documentation for this struct was generated from the following file:

• /home/runner/work/co_usb/co_usb/include/co_usb/ev/detail/handler_service.hpp