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”. TheBreadThread
is!Send
and thus remains fixed to the bread thread. - The
BreadThread
is provided an object implementing theController
trait, which determines how it runs the main event loop. - Objects implementing the
Directive
trait are used to send “messages” to theController
, telling it what operations it should run. - The
BreadThread
also creates “events”. An “event handler” can be provided to theBreadThread
in order to run something whenever an event is generated. - While the
BreadThread
is!Send
, it can createThreadHandle
s 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
Create a type that internally wraps around Key
.
Structs
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.
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.
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.
A handle to the bread thread that can be sent between threads.
Enums
Add or remove a pointer from the verified pointers list.
An error occurred during operation of breadthread
.
The result of a loop cycle.
Traits
Represents an object that is used to complete a directive process.
This object dictates what the BreadThread
will do, exactly.
Represents a directive that can be sent to a bread thread.
This object sends events to the main Controller
.
The type that a Key
can have.