Crate breadthread

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.

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.
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.

Enums

AddOrRemovePtr	Add or remove a pointer from the verified pointers list.
Error	An error occurred during operation of breadthread.
LoopCycle	The result of a loop cycle.

Traits

Completer	Represents an object that is used to complete a directive process.
Controller	This object dictates what the BreadThread will do, exactly.
Directive	Represents a directive that can be sent to a bread thread.
DirectiveAdaptor	This object sends events to the main Controller.