Flushing execution

Updated: May 27, 2022

Flushing execution functions add commands to the command buffer and then immediately flushes it.

This behavior typically happens because the execution of the API function depends on commands previously queued on the command buffer. In addition, the API function requires immediate communication with the Composition Manager.

For example, screen_get_context_property_cv() is of type flushing execution. This API function queues the command for retrieving the specified context property. Then the function proceeds to flush the command buffer, and after doing so, communicates with the Composition Manager. This function needs to flush the command buffer because the value of the property being retrieved may depend on a previously queued command, such as setting the value of the property. Therefore, the set command for the property should be processed first, before retrieving the value.

The return value from flushing execution functions indicates whether or not all commands flushed from the batch-processing queue have been executed successfully. A successful return value indicates that all queued commands were processed and executed without errors. An unsuccessful return value indicates an error in either the execution of a previously queued command, or the flushing command (the command from the call of the flushing execution function).

Note: Screen doesn't stop processing batched commands when it detects an error. All commands queued for batch processing will be processed until the batch-processing command queue is empty.