| Flutter Impeller |

Classes | Public Types | Public Member Functions | List of all members
impeller::ReactorGLES Class Reference

The reactor attempts to make thread-safe usage of OpenGL ES easier to reason about. More...

`#include <reactor_gles.h>`

## Classes
class | Worker
| A delegate implemented by a thread on which an OpenGL context is current. There may be multiple workers for the reactor to perform reactions on. In that case, it is the workers responsibility to ensure that all of them use either the same OpenGL context or multiple OpenGL contexts in the same sharegroup. More...

## Public Types
using | WorkerID = UniqueID
using | Ref = std::shared_ptr< ReactorGLES >
using | Operation = std::function< void(const ReactorGLES &reactor)>

## Public Member Functions
| ReactorGLES (std::unique_ptr< ProcTableGLES > gl)
| Create a new reactor. There are expensive and only one per application instance is necessary. More...
| ~ReactorGLES ()
| Destroy a reactor. More...
bool | IsValid () const
| If this is a valid reactor. Invalid reactors must be discarded immediately. More...
WorkerID | AddWorker (std::weak_ptr< Worker > worker)
| Adds a worker to the reactor. Each new worker must ensure that the context it manages is the same as the other workers in the reactor or in the same sharegroup. More...
bool | RemoveWorker (WorkerID id)
| Remove a previously added worker from the reactor. If the reactor has no workers, pending added operations will never run. More...
const ProcTableGLES & | GetProcTable () const
| Get the OpenGL proc. table the reactor uses to manage handles. More...
std::optional< GLuint > | GetGLHandle (const HandleGLES &handle) const
| Returns the OpenGL handle for a reactor handle if one is available. This is typically only safe to call within a reaction. That is, within a `ReactorGLES::Operation`. More...
HandleGLES | CreateHandle (HandleType type, GLuint external_handle=GL_NONE)
| Create a reactor handle. More...
void | CollectHandle (HandleGLES handle)
| Collect a reactor handle. More...
void | SetDebugLabel (const HandleGLES &handle, std::string label)
| Set the debug label on a reactor handle. More...
bool | AddOperation (Operation operation)
| Adds an operation that the reactor runs on a worker that ensures that an OpenGL context is current. More...
bool | React ()
| Perform a reaction on the current thread if able. More...

## Detailed Description

The reactor attempts to make thread-safe usage of OpenGL ES easier to reason about.

In the other Impeller backends (like Metal and Vulkan), resources can be created, used, and deleted on any thread with relatively few restrictions. However, OpenGL resources can only be created, used, and deleted on a thread on which an OpenGL context (or one in the same sharegroup) is current.

There aren't too many OpenGL contexts to go around and making the caller reason about the timing and threading requirement only when the OpenGL backend is in use is tedious. To work around this tedium, there is an abstraction between the resources and their handles in OpenGL. The reactor is this abstraction.

The reactor is thread-safe and can created, used, and collected on any thread.

Reactor handles `HandleGLES` can be created, used, and collected on any thread. These handles can be to textures, buffers, etc..

Operations added to the reactor are guaranteed to run on a worker within a finite amount of time unless the reactor itself is torn down or there are no workers. These operations may run on the calling thread immediately if a worker is active on the current thread and can perform reactions. The operations are guaranteed to run with an OpenGL context current and all reactor handles having live OpenGL handle counterparts.

Creating a handle in the reactor doesn't mean an OpenGL handle is created immediately. OpenGL handles become live before the next reaction. Similarly, dropping the last reference to a reactor handle means that the OpenGL handle will be deleted at some point in the near future.

Definition at line 55 of file reactor_gles.h.

## Member Typedef Documentation

## ◆ Operation

using impeller::ReactorGLES::Operation = std::function<void(const ReactorGLES& reactor)>

Definition at line 195 of file reactor_gles.h.

## ◆ Ref

using impeller::ReactorGLES::Ref = std::shared_ptr<ReactorGLES>

Definition at line 86 of file reactor_gles.h.

## ◆ WorkerID

using impeller::ReactorGLES::WorkerID = UniqueID

Definition at line 57 of file reactor_gles.h.

## Constructor & Destructor Documentation

## ◆ ReactorGLES()

impeller::ReactorGLES::ReactorGLES | ( | std::unique_ptr< ProcTableGLES > | gl | ) |
| explicit

Create a new reactor. There are expensive and only one per application instance is necessary.

Parameters

  [in] | gl | The proc table for GL access. This is necessary for the reactor to be able to create and collect OpenGL handles.

Definition at line 15 of file reactor_gles.cc.

16 : proc_table_(std::move(gl)) {
17 if (!proc_table_ || !proc_table_->IsValid()) {
18 VALIDATION_LOG << "Proc table was invalid.";
19 return;
20 }
21 can_set_debug_labels_ = proc_table_->GetDescription()->HasDebugExtension();
22 is_valid_ = true;
23 }

References VALIDATION_LOG.

## ◆ ~ReactorGLES()

impeller::ReactorGLES::~ReactorGLES | ( |  | ) |
| default

Destroy a reactor.

## Member Function Documentation

## ◆ AddOperation()

bool impeller::ReactorGLES::AddOperation | ( | Operation | operation | ) |

Adds an operation that the reactor runs on a worker that ensures that an OpenGL context is current.

This operation is not guaranteed to run immediately. It will complete in a finite amount of time on any thread as long as there is a reactor worker and the reactor itself is not being torn down.

Parameters

  [in] | operation | The operation

Returns
  If the operation was successfully queued for completion.

Definition at line 71 of file reactor_gles.cc.

71 {
72 if (!operation) {
73 return false;
74 }
75 {
76 Lock ops_lock(ops_mutex_);
77 ops_.emplace_back(std::move(operation));
78 }
79 // Attempt a reaction if able but it is not an error if this isn't possible.
80 [[maybe_unused]] auto result = React();
81 return true;
82 }

References React().

## ◆ AddWorker()

ReactorGLES::WorkerID impeller::ReactorGLES::AddWorker | ( | std::weak_ptr< Worker > | worker | ) |

Adds a worker to the reactor. Each new worker must ensure that the context it manages is the same as the other workers in the reactor or in the same sharegroup.

Parameters

  [in] | worker | The worker

Returns
  The worker identifier. This identifier can be used to remove the worker from the reactor later.

Definition at line 31 of file reactor_gles.cc.

31 {
32 Lock lock(workers_mutex_);
33 auto id = WorkerID{};
34 workers_[id] = std::move(worker);
35 return id;
36 }

## ◆ CollectHandle()

void impeller::ReactorGLES::CollectHandle | ( | HandleGLES | handle | ) |

Collect a reactor handle.

            This can be called on any thread. Even one that doesn't have
            an OpenGL context.

Parameters

  [in] | handle | The reactor handle handle

Definition at line 153 of file reactor_gles.cc.

153 {
154 WriterLock handles_lock(handles_mutex_);
155 if (auto found = handles_.find(handle); found != handles_.end()) {
156 found->second.pending_collection = true;
157 }
158 }

## ◆ CreateHandle()

HandleGLES impeller::ReactorGLES::CreateHandle | ( | HandleType | type,
|  | GLuint | external_handle = `GL_NONE`
| ) |  |

Create a reactor handle.

            This can be called on any thread. Even one that doesn't have
            an OpenGL context.

Parameters

  [in] | type | The type of handle to create.
  [in] | external_handle | An already created GL handle if one exists.

Returns
  The reactor handle.

Definition at line 133 of file reactor_gles.cc.

133 {
134 if (type == HandleType::kUnknown) {
135 return HandleGLES::DeadHandle();
136 }
137 auto new_handle = HandleGLES::Create(type);
138 if (new_handle.IsDead()) {
139 return HandleGLES::DeadHandle();
140 }
141 WriterLock handles_lock(handles_mutex_);
142
143 std::optional<GLuint> gl_handle;
144 if (external_handle != GL_NONE) {
145 gl_handle = external_handle;
146 } else if (CanReactOnCurrentThread()) {
147 gl_handle = CreateGLHandle(GetProcTable(), type);
148 }
149 handles_[new_handle] = LiveHandle{gl_handle};
150 return new_handle;
151 }

References impeller::CreateGLHandle(), impeller::HandleGLES::DeadHandle(), GetProcTable(), impeller::kUnknown, and type.

## ◆ GetGLHandle()

std::optional< GLuint > impeller::ReactorGLES::GetGLHandle | ( | const HandleGLES & | handle | ) | const

Returns the OpenGL handle for a reactor handle if one is available. This is typically only safe to call within a reaction. That is, within a `ReactorGLES::Operation`.

Asking for the OpenGL handle before the reactor has a chance to reactor will return `std::nullopt`.

This can be called on any thread but is typically useless outside of a reaction since the handle is useless outside of a reactor operation.

Parameters

  [in] | handle | The reactor handle.

Returns
  The OpenGL handle if the reactor has had a chance to react. `std::nullopt` otherwise.

Definition at line 53 of file reactor_gles.cc.

53 {
54 ReaderLock handles_lock(handles_mutex_);
55 if (auto found = handles_.find(handle); found != handles_.end()) {
56 if (found->second.pending_collection) {
57 VALIDATION_LOG
58 << "Attempted to acquire a handle that was pending collection.";
59 return std::nullopt;
60 }
61 if (!found->second.name.has_value()) {
62 VALIDATION_LOG << "Attempt to acquire a handle outside of an operation.";
63 return std::nullopt;
64 }
65 return found->second.name;
66 }
67 VALIDATION_LOG << "Attempted to acquire an invalid GL handle.";
68 return std::nullopt;
69 }

References VALIDATION_LOG.

Referenced by impeller::LinkProgram().

## ◆ GetProcTable()

const ProcTableGLES & impeller::ReactorGLES::GetProcTable | ( |  | ) | const

Get the OpenGL proc. table the reactor uses to manage handles.

Returns
  The proc table.

Definition at line 48 of file reactor_gles.cc.

48 {
49 FML_DCHECK(IsValid());
50 return *proc_table_;
51 }

References IsValid().

Referenced by CreateHandle(), impeller::BlitCopyBufferToTextureCommandGLES::Encode(), impeller::BlitCopyTextureToTextureCommandGLES::Encode(), impeller::BlitCopyTextureToBufferCommandGLES::Encode(), impeller::BlitResizeTextureCommandGLES::Encode(), impeller::EncodeCommandsInReactor(), and impeller::LinkProgram().

## ◆ IsValid()

bool impeller::ReactorGLES::IsValid | ( |  | ) | const

If this is a valid reactor. Invalid reactors must be discarded immediately.

Returns
  If this reactor is valid.

Definition at line 27 of file reactor_gles.cc.

27 {
28 return is_valid_;
29 }

Referenced by GetProcTable().

## ◆ React()

bool impeller::ReactorGLES::React | ( |  | ) |

Perform a reaction on the current thread if able.

            It is safe to call this simultaneously from multiple threads
            at the same time.

Returns
  If a reaction was performed on the calling thread.

Definition at line 160 of file reactor_gles.cc.

160 {
161 if (!CanReactOnCurrentThread()) {
162 return false;
163 }
164 TRACE_EVENT0("impeller", "ReactorGLES::React");
165 while (HasPendingOperations()) {
166 // Both the raster thread and the IO thread can flush queued operations.
167 // Ensure that execution of the ops is serialized.
168 Lock execution_lock(ops_execution_mutex_);
169
170 if (!ReactOnce()) {
171 return false;
172 }
173 }
174 return true;
175 }

Referenced by AddOperation().

## ◆ RemoveWorker()

bool impeller::ReactorGLES::RemoveWorker | ( | WorkerID | id | ) |

Remove a previously added worker from the reactor. If the reactor has no workers, pending added operations will never run.

Parameters

  [in] | id | The worker identifier previously returned by `AddWorker`.

Returns
  If a worker with the given identifer was successfully removed from the reactor.

Definition at line 38 of file reactor_gles.cc.

38 {
39 Lock lock(workers_mutex_);
40 return workers_.erase(worker) == 1;
41 }

## ◆ SetDebugLabel()

void impeller::ReactorGLES::SetDebugLabel | ( | const HandleGLES & | handle,
|  | std::string | label
| ) |  |

Set the debug label on a reactor handle.

            This call ensures that the OpenGL debug label is propagated to
            even the OpenGL handle hasn't been created at the time the
            caller sets the label.

Parameters

  [in] | handle | The handle
  [in] | label | The label

Definition at line 278 of file reactor_gles.cc.

278 {
279 if (!can_set_debug_labels_) {
280 return;
281 }
282 if (handle.IsDead()) {
283 return;
284 }
285 WriterLock handles_lock(handles_mutex_);
286 if (auto found = handles_.find(handle); found != handles_.end()) {
287 found->second.pending_debug_label = std::move(label);
288 }
289 }

References impeller::HandleGLES::IsDead().

The documentation for this class was generated from the following files:

- impeller/renderer/backend/gles/reactor_gles.h
- impeller/renderer/backend/gles/reactor_gles.cc

impeller::ReactorGLES::GetProcTable
const ProcTableGLES & GetProcTable() const
Get the OpenGL proc. table the reactor uses to manage handles.
Definition: reactor_gles.cc:48
impeller::HandleGLES::DeadHandle
static HandleGLES DeadHandle()
Creates a dead handle.
Definition: handle_gles.h:45
impeller::HandleType::kUnknown
@ kUnknown
impeller::ReactorGLES::React
bool React()
Perform a reaction on the current thread if able.
Definition: reactor_gles.cc:160
impeller::ReactorGLES::WorkerID
UniqueID WorkerID
Definition: reactor_gles.h:57
type
GLenum type
Definition: blit_command_gles.cc:127
impeller::ReactorGLES::IsValid
bool IsValid() const
If this is a valid reactor. Invalid reactors must be discarded immediately.
Definition: reactor_gles.cc:27
impeller::CreateGLHandle
static std::optional< GLuint > CreateGLHandle(const ProcTableGLES &gl, HandleType type)
Definition: reactor_gles.cc:84
VALIDATION_LOG
#define VALIDATION_LOG
Definition: validation.h:91
impeller::interop::Create
ScopedObject< Object > Create(CtorArgs &&... args)
Definition: object.h:160