| Flutter Impeller |

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

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 | 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...
std::optional< GLsync > | GetGLFence (const HandleGLES &handle) const
HandleGLES | CreateHandle (HandleType type, GLuint external_handle=GL_NONE)
| Create a reactor handle. More...
HandleGLES | CreateUntrackedHandle (HandleType type) const
| Create a handle that is not managed by `ReactorGLES`. More...
void | CollectHandle (HandleGLES handle)
| Collect a reactor handle. More...
void | SetDebugLabel (const HandleGLES &handle, std::string_view label)
| Set the debug label on a reactor handle. More...
bool | CanSetDebugLabels () const
| Whether the device is capable of writing debug labels. More...
bool | AddOperation (Operation operation, bool defer=false)
| Adds an operation that the reactor runs on a worker that ensures that an OpenGL context is current. More...
bool | RegisterCleanupCallback (const HandleGLES &handle, const fml::closure &callback)
| Register a cleanup callback that will be invokved with the provided user data when the handle is destroyed. 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 57 of file reactor_gles.h.

## Member Typedef Documentation

## ◆ Operation

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

Definition at line 214 of file reactor_gles.h.

## ◆ WorkerID

using impeller::ReactorGLES::WorkerID = UniqueID

Definition at line 59 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 73 of file reactor_gles.cc.

74 : proc_table_(std::move(gl)) {
75 if (!proc_table_ || !proc_table_->IsValid()) {
76 VALIDATION_LOG << "Proc table was invalid.";
77 return;
78 }
79 can_set_debug_labels_ = proc_table_->GetDescription()->HasDebugExtension();
80 is_valid_ = true;
81 }
VALIDATION_LOG
#define VALIDATION_LOG
Definition: validation.h:91

References VALIDATION_LOG.

## ◆ ~ReactorGLES()

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

Destroy a reactor.

Definition at line 83 of file reactor_gles.cc.

83 {
84 if (CanReactOnCurrentThread()) {
85 for (auto& handle : handles_) {
86 if (handle.second.name.has_value()) {
87 CollectGLHandle(*proc_table_, handle.first.GetType(),
88 handle.second.name.value());
89 }
90 }
91 proc_table_->Flush();
92 }
93 }

## Member Function Documentation

## ◆ AddOperation()

bool impeller::ReactorGLES::AddOperation | ( | Operation | operation,
|  | bool | defer = `false`
| ) |  |

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
  [in] | defer | If false, the reactor attempts to React after adding this operation.

Returns
  If the operation was successfully queued for completion.

Definition at line 173 of file reactor_gles.cc.

173 {
174 if (!operation) {
175 return false;
176 }
177 auto thread_id = std::this_thread::get_id();
178 {
179 Lock ops_lock(ops_mutex_);
180 ops_[thread_id].emplace_back(std::move(operation));
181 }
182 // Attempt a reaction if able but it is not an error if this isn't possible.
183 if (!defer) {
184 [[maybe_unused]] auto result = React();
185 }
186 return true;
187 }
impeller::ReactorGLES::React
bool React()
Perform a reaction on the current thread if able.
Definition: reactor_gles.cc:252

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 103 of file reactor_gles.cc.

103 {
104 Lock lock(workers_mutex_);
105 auto id = WorkerID{};
106 workers_[id] = std::move(worker);
107 return id;
108 }
impeller::ReactorGLES::WorkerID
UniqueID WorkerID
Definition: reactor_gles.h:59

## ◆ CanSetDebugLabels()

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

Whether the device is capable of writing debug labels.

            This function is useful for short circuiting expensive debug
            labeling.

Definition at line 99 of file reactor_gles.cc.

99 {
100 return can_set_debug_labels_;
101 }

## ◆ 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 235 of file reactor_gles.cc.

235 {
236 if (handle.untracked_id_.has_value()) {
237 LiveHandle live_handle(GLStorage{.integer = handle.untracked_id_.value()});
238 live_handle.pending_collection = true;
239 WriterLock handles_lock(handles_mutex_);
240 handles_[handle] = std::move(live_handle);
241 } else {
242 WriterLock handles_lock(handles_mutex_);
243 if (auto found = handles_.find(handle); found != handles_.end()) {
244 if (!found->second.pending_collection) {
245 handles_to_collect_count_ += 1;
246 }
247 found->second.pending_collection = true;
248 }
249 }
250 }

## ◆ 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 214 of file reactor_gles.cc.

214 {
215 if (type == HandleType::kUnknown) {
216 return HandleGLES::DeadHandle();
217 }
218 auto new_handle = HandleGLES::Create(type);
219 if (new_handle.IsDead()) {
220 return HandleGLES::DeadHandle();
221 }
222
223 std::optional<ReactorGLES::GLStorage> gl_handle;
224 if (external_handle != GL_NONE) {
225 gl_handle = ReactorGLES::GLStorage{.handle = external_handle};
226 } else if (CanReactOnCurrentThread()) {
227 gl_handle = CreateGLHandle(GetProcTable(), type);
228 }
229
230 WriterLock handles_lock(handles_mutex_);
231 handles_[new_handle] = LiveHandle{gl_handle};
232 return new_handle;
233 }
type
GLenum type
Definition: blit_command_gles.cc:151
impeller::HandleGLES::DeadHandle
static HandleGLES DeadHandle()
Creates a dead handle.
Definition: handle_gles.h:44
impeller::ReactorGLES::GetProcTable
const ProcTableGLES & GetProcTable() const
Get the OpenGL proc. table the reactor uses to manage handles.
Definition: reactor_gles.cc:122
impeller::HandleType::kUnknown
@ kUnknown

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

## ◆ CreateUntrackedHandle()

HandleGLES impeller::ReactorGLES::CreateUntrackedHandle | ( | HandleType | type | ) | const

Create a handle that is not managed by `ReactorGLES`.

This behaves just like `CreateHandle` but it doesn't add the handle to ReactorGLES::handles_ and the creation is executed synchronously, so it must be called from a proper thread. The benefit of this is that it avoid synchronization and hash table lookups when creating/accessing the handle.

Parameters

  type | The type of handle to create.

Returns
  The reactor handle.

Definition at line 203 of file reactor_gles.cc.

203 {
204 FML_DCHECK(CanReactOnCurrentThread());
205 auto new_handle = HandleGLES::Create(type);
206 std::optional<ReactorGLES::GLStorage> gl_handle =
207 CreateGLHandle(GetProcTable(), type);
208 if (gl_handle.has_value()) {
209 new_handle.untracked_id_ = gl_handle.value().integer;
210 }
211 return new_handle;
212 }

References GetProcTable(), and type.

Referenced by impeller::EncodeCommandsInReactor().

## ◆ GetGLFence()

std::optional< GLsync > impeller::ReactorGLES::GetGLFence | ( | const HandleGLES & | handle | ) | const

Definition at line 162 of file reactor_gles.cc.

162 {
163 if (handle.GetType() != HandleType::kFence) {
164 return std::nullopt;
165 }
166 std::optional<ReactorGLES::GLStorage> gl_handle = GetHandle(handle);
167 if (gl_handle.has_value()) {
168 return gl_handle->sync;
169 }
170 return std::nullopt;
171 }
impeller::HandleType::kFence
@ kFence

References impeller::HandleGLES::GetType(), and impeller::kFence.

## ◆ 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 151 of file reactor_gles.cc.

151 {
152 if (handle.GetType() == HandleType::kFence) {
153 return std::nullopt;
154 }
155 std::optional<ReactorGLES::GLStorage> gl_handle = GetHandle(handle);
156 if (gl_handle.has_value()) {
157 return gl_handle->handle;
158 }
159 return std::nullopt;
160 }

References impeller::HandleGLES::GetType(), and impeller::kFence.

Referenced by impeller::EncodeCommandsInReactor(), and 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 122 of file reactor_gles.cc.

122 {
123 FML_DCHECK(IsValid());
124 return *proc_table_;
125 }
impeller::ReactorGLES::IsValid
bool IsValid() const
If this is a valid reactor. Invalid reactors must be discarded immediately.
Definition: reactor_gles.cc:95

References IsValid().

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

## ◆ 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 95 of file reactor_gles.cc.

95 {
96 return is_valid_;
97 }

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 252 of file reactor_gles.cc.

252 {
253 if (!CanReactOnCurrentThread()) {
254 return false;
255 }
256 TRACE_EVENT0("impeller", "ReactorGLES::React");
257 while (HasPendingOperations()) {
258 if (!ReactOnce()) {
259 return false;
260 }
261 }
262 return true;
263 }

Referenced by AddOperation().

## ◆ RegisterCleanupCallback()

bool impeller::ReactorGLES::RegisterCleanupCallback | ( | const HandleGLES & | handle,
|  | const fml::closure & | callback
| ) |  |

Register a cleanup callback that will be invokved with the provided user data when the handle is destroyed.

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] | handle | The handle to attach the cleanup to.
  [in] | callback | The cleanup callback to execute.

Returns
  If the operation was successfully queued for completion.

Definition at line 189 of file reactor_gles.cc.

190 {
191 if (handle.IsDead()) {
192 return false;
193 }
194 FML_DCHECK(!handle.untracked_id_.has_value());
195 WriterLock handles_lock(handles_mutex_);
196 if (auto found = handles_.find(handle); found != handles_.end()) {
197 found->second.callback = fml::ScopedCleanupClosure(callback);
198 return true;
199 }
200 return false;
201 }

References impeller::HandleGLES::IsDead().

## ◆ 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 110 of file reactor_gles.cc.

110 {
111 Lock lock(workers_mutex_);
112 return workers_.erase(worker) == 1;
113 }

## ◆ SetDebugLabel()

void impeller::ReactorGLES::SetDebugLabel | ( | const HandleGLES & | handle,
|  | std::string_view | 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 387 of file reactor_gles.cc.

388 {
389 FML_DCHECK(handle.GetType() != HandleType::kFence);
390 if (!can_set_debug_labels_) {
391 return;
392 }
393 if (handle.IsDead()) {
394 return;
395 }
396 if (handle.untracked_id_.has_value()) {
397 FML_DCHECK(CanReactOnCurrentThread());
398 const auto& gl = GetProcTable();
399 gl.SetDebugLabel(ToDebugResourceType(handle.GetType()),
400 handle.untracked_id_.value(), label);
401 } else {
402 WriterLock handles_lock(handles_mutex_);
403 if (auto found = handles_.find(handle); found != handles_.end()) {
404 found->second.pending_debug_label = label;
405 }
406 }
407 }
impeller::ToDebugResourceType
static DebugResourceType ToDebugResourceType(HandleType type)
Definition: reactor_gles.cc:265

References GetProcTable(), impeller::HandleGLES::GetType(), impeller::HandleGLES::IsDead(), impeller::kFence, and impeller::ToDebugResourceType().

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