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.
	~ReactorGLES ()
	Destroy a reactor.
bool	IsValid () const
	If this is a valid reactor. Invalid reactors must be discarded immediately.
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.
bool	RemoveWorker (WorkerID id)
	Remove a previously added worker from the reactor. If the reactor has no workers, pending added operations will never run.
const ProcTableGLES &	GetProcTable () const
	Get the OpenGL proc. table the reactor uses to manage handles.
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.
HandleGLES	CreateHandle (HandleType type)
	Create a reactor handle.
void	CollectHandle (HandleGLES handle)
	Collect a reactor handle.
void	SetDebugLabel (const HandleGLES &handle, std::string label)
	Set the debug label on a reactor handle.
bool	AddOperation (Operation operation)
	Adds an operation that the reactor runs on a worker that ensures that an OpenGL context is current.
bool	React ()
	Perform a reaction on the current thread if able.

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 56 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 87 of file reactor_gles.h.

WorkerID

using impeller::ReactorGLES::WorkerID = UniqueID

Definition at line 58 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.

    : proc_table_(std::move(gl)) {
  if (!proc_table_ || !proc_table_->IsValid()) {
    VALIDATION_LOG << "Proc table was invalid.";
    return;
  }
  can_set_debug_labels_ = proc_table_->GetDescription()->HasDebugExtension();
  is_valid_ = true;
}

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

                                                  {
  if (!operation) {
    return false;
  }
  {
    Lock ops_lock(ops_mutex_);
    ops_.emplace_back(std::move(operation));
  }
  // Attempt a reaction if able but it is not an error if this isn't possible.
  [[maybe_unused]] auto result = React();
  return true;
}

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.

                                                                     {
  Lock lock(workers_mutex_);
  auto id = WorkerID{};
  workers_[id] = std::move(worker);
  return id;
}

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

                                                 {
  WriterLock handles_lock(handles_mutex_);
  if (auto found = handles_.find(handle); found != handles_.end()) {
    found->second.pending_collection = true;
  }
}

CreateHandle()

HandleGLES impeller::ReactorGLES::CreateHandle

(

HandleType

type

)

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.

Returns

The reactor handle.

Definition at line 133 of file reactor_gles.cc.

                                                    {
  if (type == HandleType::kUnknown) {
    return HandleGLES::DeadHandle();
  }
  auto new_handle = HandleGLES::Create(type);
  if (new_handle.IsDead()) {
    return HandleGLES::DeadHandle();
  }
  WriterLock handles_lock(handles_mutex_);
  auto gl_handle = CanReactOnCurrentThread()
                       ? CreateGLHandle(GetProcTable(), type)
                       : std::nullopt;
  handles_[new_handle] = LiveHandle{gl_handle};
  return new_handle;
}

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.

                                                                           {
  ReaderLock handles_lock(handles_mutex_);
  if (auto found = handles_.find(handle); found != handles_.end()) {
    if (found->second.pending_collection) {
      VALIDATION_LOG
          << "Attempted to acquire a handle that was pending collection.";
      return std::nullopt;
    }
    if (!found->second.name.has_value()) {
      VALIDATION_LOG << "Attempt to acquire a handle outside of an operation.";
      return std::nullopt;
    }
    return found->second.name;
  }
  VALIDATION_LOG << "Attempted to acquire an invalid GL handle.";
  return std::nullopt;
}

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.

                                                     {
  FML_DCHECK(IsValid());
  return *proc_table_;
}

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.

                                {
  return is_valid_;
}

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

                        {
  if (!CanReactOnCurrentThread()) {
    return false;
  }
  TRACE_EVENT0("impeller", "ReactorGLES::React");
  while (HasPendingOperations()) {
    // Both the raster thread and the IO thread can flush queued operations.
    // Ensure that execution of the ops is serialized.
    Lock execution_lock(ops_execution_mutex_);
 
    if (!ReactOnce()) {
      return false;
    }
  }
  return true;
}

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.

                                              {
  Lock lock(workers_mutex_);
  return workers_.erase(worker) == 1;
}

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

                                                                         {
  if (!can_set_debug_labels_) {
    return;
  }
  if (handle.IsDead()) {
    return;
  }
  WriterLock handles_lock(handles_mutex_);
  if (auto found = handles_.find(handle); found != handles_.end()) {
    found->second.pending_debug_label = std::move(label);
  }
}

---

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