Crate breadthread[−][src]

Expand description

breadthread is an abstraction for what I’ve noticed is a very common pattern for low-level graphics APIs to have:

One thread is designated the “GUI Thread”. All GUI operations must occur in this thread.
Primitives are thread-unsafe and can only be used safely in the GUI thread.
In order to run the framework, an event loop function has to be called in a loop.
This “main loop” produces events.

In order to abstract over this model in a not just memory-safe, but thread-safe way, the breadthread package:

Provides the BreadThread object. When this object is instantiated, the thread it’s instantiated in becomes the “bread thread”. The BreadThread is !Send and thus remains fixed to the bread thread.
The BreadThread is provided an object implementing the Controller trait, which determines how it runs the main event loop.
Objects implementing the Directive trait are used to send “messages” to the Controller, telling it what operations it should run.
The BreadThread also creates “events”. An “event handler” can be provided to the BreadThread in order to run something whenever an event is generated.
While the BreadThread is !Send, it can create ThreadHandles that can be sent to other threads.
When the first ThreadHandle is created, the “directive thread” is spawned. This thread listens for events and then pushes them into the controller’s directive queue.
When the ThreadHandle is used from another thread, it sends its directives to the directive thread. However, if it is used from the bread thread, it forwards its directives straight to the controller.

Features

breadthread uses mutexes internally. When the pl feature is enabled, it uses parking_lot mutexes instead of std::sync mutexes. This may be useful in programs that already use parking_lot.

Macros

key_type

Create a type that internally wraps around Key.

Structs

BreadThread

The object representing the bread thread. The thread this object is created in is the bread thread, and it cannot be moved out of the bread thread.

Key

A key. This is a wrapper around a non-zero usize that usually represents a pointer. This object represents a foreign object, usually managed by the API that the bread thread is managing. This is provided as a utility so you know that the pointer you have is a pointer to the object you’re talking about. The thread itself is able to verify that the pointer not only is not dangling, but refers to the type you are talking about.

PinnedThreadHandle

A handle to the bread thread that is locked to its thread. This allows it to omit a call to thread::current().id() which saves time.

ThreadHandle

A handle to the bread thread that can be sent between threads.