Flushing execution describes API functions where the command from the function call is queued for batch processing, and then the command buffer is immediately flushed to process all queued commands—previously queued ones included.
This behavior (adding commands to the command buffer and then immediately flushing it) typically happens because the execution of the API function is dependent on commands previously queued on the command buffer. In addition, the API function requires immediate communication with the Screen and Windowing services.
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 Screen and Windowing services. 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 indiates 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).