KHR_fence_sync

EGL_KHR_fence_sync
GL_OES_EGL_sync
VG_KHR_EGL_sync

Acorn Pooley
Gary King
Gregory Prisament
Jon Leech

Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com)
Jon Leech (jon 'at' alumni.caltech.edu)

Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

Complete. Approved by the EGL Working Group on March 3, 2010.
Approved by the Khronos Board of Promoters on April 30, 2010.

Version 24, January 31, 2014

EGL Extension #20
OpenGL ES Extension #75
OpenVG Extension #7

Requires EGL 1.1

This extension is written against the wording of the EGL 1.2
Specification.

This extension introduces the concept of "sync objects" into EGL.
Sync objects are a synchronization primitive, representing events
whose completion can be tested or waited upon.  This extension
borrows heavily from the GL_ARB_sync extension and introduces a type
of sync object known as a "fence sync object" comparable to the
OpenGL fence sync object. The specification is designed to allow
additional types of sync objects to be easily introduced in later
extensions.

Fence sync objects have corresponding fence commands, which are
inserted into a client API command stream at the time the fence sync
is created. A fence sync object is used to wait for completion of
the corresponding fence command. This allows applications to request
a partial Finish of an API command stream, wherein all commands
issued in a particular client API context will be forced to complete
before control is returned to the calling thread.

This document describes three different extension strings
collectively. The "EGL_KHR_fence_sync" string indicates that fence
syncs and the corresponding interfaces (to create and place a fence,
destroy, query, and wait on) are supported.

The remaining extensions list valid client APIs for fence syncs. The
"GL_OES_EGL_sync" string indicates that a fence sync object can be
created in association with a fence command placed in the command
stream of a bound OpenGL ES context. The "VG_KHR_EGL_sync" string
indicates the same thing for a bound OpenVG context.

/*
 * EGLSyncKHR is an opaque handle to an EGL sync object
 */
typedef void* EGLSyncKHR;

/*
 * EGLTimeKHR is a 64-bit unsigned integer representing intervals
 * in nanoseconds.
 */
#include <khrplatform.h>
typedef khronos_utime_nanoseconds_t EGLTimeKHR;

EGLSyncKHR eglCreateSyncKHR(
                    EGLDisplay dpy,
                    EGLenum type,
                    const EGLint *attrib_list);

EGLBoolean eglDestroySyncKHR(
                    EGLDisplay dpy,
                    EGLSyncKHR sync);

EGLint eglClientWaitSyncKHR(
                    EGLDisplay dpy,
                    EGLSyncKHR sync,
                    EGLint flags,
                    EGLTimeKHR timeout);

EGLBoolean eglGetSyncAttribKHR(
                    EGLDisplay dpy,
                    EGLSyncKHR sync,
                    EGLint attribute,
                    EGLint *value);

Accepted by the <type> parameter of eglCreateSyncKHR, and returned
in <value> when eglGetSyncAttribKHR is called with <attribute>
EGL_SYNC_TYPE_KHR:

EGL_SYNC_FENCE_KHR                      0x30F9

Accepted by the <attribute> parameter of eglGetSyncAttribKHR:

EGL_SYNC_TYPE_KHR                       0x30F7
EGL_SYNC_STATUS_KHR                     0x30F1
EGL_SYNC_CONDITION_KHR                  0x30F8

Returned in <value> when eglGetSyncAttribKHR is called with
<attribute> EGL_SYNC_STATUS_KHR:

EGL_SIGNALED_KHR                        0x30F2
EGL_UNSIGNALED_KHR                      0x30F3

Returned in <value> when eglGetSyncAttribKHR is called with
<attribute> EGL_SYNC_CONDITION_KHR:

EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR    0x30F0

Accepted in the <flags> parameter of eglClientWaitSyncKHR:

EGL_SYNC_FLUSH_COMMANDS_BIT_KHR         0x0001

Accepted in the <timeout> parameter of eglClientWaitSyncKHR:

EGL_FOREVER_KHR                         0xFFFFFFFFFFFFFFFFull

Returned by eglClientWaitSyncKHR:

EGL_TIMEOUT_EXPIRED_KHR                 0x30F5
EGL_CONDITION_SATISFIED_KHR             0x30F6

Returned by eglCreateSyncKHR in the event of an error:

EGL_NO_SYNC_KHR                         ((EGLSyncKHR)0)

Add a new subsection at the end of Section 3.8, page 43
(Synchronization Primitives)

"3.8.1  Sync Objects

In addition to the aforementioned synchronization functions, which
provide an efficient means of serializing client and native API
operations within a thread, <sync objects> are provided to enable
synchronization of client API operations between threads and/or
between API contexts. Sync objects may be tested or waited upon by
application threads.

Sync objects have a status with two possible states: <signaled> and
<unsignaled>. Initially, sync objects are unsignaled. EGL may be
asked to wait for a sync object to become signaled, or a sync
object's status may be queried.

Depending on the type of a sync object, its status may be changed
either by an external event, or by explicitly signaling and
unsignaling the sync.

Sync objects are associated with an EGLDisplay when they are
created, and have <attributes> defining additional aspects of the
sync object. All sync objects include attributes for their type and
their status. Additional attributes are discussed below
for different types of sync objects.

<Fence sync objects> are created in association with a <fence
command> in a client API. When the client API executes the fence
command, an event is generated which signals the corresponding fence
sync object. Fence sync objects may not be explicitly signaled, and
may only change their status once, from the initial unsignaled
status to signaled. Fence sync objects may be used to wait for
partial completion of a client API command stream, as a more
flexible form of glFinish / vgFinish.

The command

    EGLSyncKHR eglCreateSyncKHR(
                        EGLDisplay dpy,
                        EGLenum type,
                        const EGLint *attrib_list);

creates a sync object of the specified <type> associated with the
specified display <dpy>, and returns a handle to the new object.
<attrib_list> is an attribute-value list specifying other attributes
of the sync object, terminated by an attribute entry EGL_NONE.
Attributes not specified in the list will be assigned their default
values.

If <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In
this case <attrib_list> must be NULL or empty (containing only
EGL_NONE). Attributes of the fence sync object are
set as follows:

  Attribute Name         Initial Attribute Value(s)
  ---------------        --------------------------
  EGL_SYNC_TYPE_KHR      EGL_SYNC_FENCE_KHR
  EGL_SYNC_STATUS_KHR    EGL_UNSIGNALED_KHR
  EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR

When a fence sync object is created, eglCreateSyncKHR also inserts a
fence command into the command stream of the bound client API's
current context (i.e., the context returned by
eglGetCurrentContext), and associates it with the newly created sync
object.

When the condition of the sync object is satisfied by the fence
command, the sync is signaled by the associated client API context,
causing any eglClientWaitSyncKHR commands (see below) blocking on
<sync> to unblock. The only condition currently supported is
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by
completion of the fence command corresponding to the sync object,
and all preceding commands in the associated client API context's
command stream. The sync object will not be signaled until all
effects from these commands on the client API's internal and
framebuffer state are fully realized. No other state is affected by
execution of the fence command.

Each client API which supports fence commands indicates this support
in the form of a client API extension. If the GL_OES_EGL_sync
extension is supported by OpenGL ES (either version 1.x or 2.0), a
fence sync object may be created when the currently bound API is
OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG,
a fence sync object may be created when the currently bound API is
OpenVG.

Errors
------

  * If <dpy> is not the name of a valid, initialized EGLDisplay,
    EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
    generated.
  * If <attrib_list> is neither NULL nor empty (containing only
    EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE
    error is generated.
  * If <type> is not a supported type of sync object,
    EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
    generated.
  * If <type> is EGL_SYNC_FENCE_KHR and no context is current for
    the bound API (i.e., eglGetCurrentContext returns
    EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
    EGL_BAD_MATCH error is generated.
  * If <type> is EGL_SYNC_FENCE_KHR and <dpy> does not match the
    EGLDisplay of the currently bound context for the currently
    bound client API (the EGLDisplay returned by
    eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
    EGL_BAD_MATCH error is generated.
  * If <type> is EGL_SYNC_FENCE_KHR and the currently bound client
    API does not support the client API extension indicating it can
    place fence commands, then EGL_NO_SYNC_KHR is returned and an
    EGL_BAD_MATCH error is generated.

The command

    EGLint eglClientWaitSyncKHR(
                        EGLDisplay dpy,
                        EGLSyncKHR sync,
                        EGLint flags,
                        EGLTimeKHR timeout);

blocks the calling thread until the specified sync object <sync> is
signaled, or until <timeout> nanoseconds have passed.

More than one eglClientWaitSyncKHR may be outstanding on the same
<sync> at any given time. When there are multiple threads blocked on
the same <sync> and the sync object is signaled, all such threads
are released, but the order in which they are released is not
defined.

If the value of <timeout> is zero, then eglClientWaitSyncKHR simply
tests the current status of <sync>. If the value of <timeout> is the
special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not
time out. For all other values, <timeout> is adjusted to the closest
value allowed by the implementation-dependent timeout accuracy,
which may be substantially longer than one nanosecond.

eglClientWaitSyncKHR returns one of three status values describing
the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR
indicates that the specified timeout period expired before <sync>
was signaled, or if <timeout> is zero, indicates that <sync> is
not signaled. A return value of EGL_CONDITION_SATISFIED_KHR
indicates that <sync> was signaled before the timeout expired, which
includes the case when <sync> was already signaled when
eglClientWaitSyncKHR was called. If an error occurs then an error is
generated and EGL_FALSE is returned.

If the sync object being blocked upon will not be signaled in finite
time (for example, by an associated fence command issued previously,
but not yet flushed to the graphics pipeline), then
eglClientWaitSyncKHR may wait forever. To help prevent this behavior
(footnote1), if the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in
<flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is
called, then the equivalent of Flush() will be performed for the
current API context (i.e., the context returned by
eglGetCurrentContext()) before blocking on <sync>. If no context is
current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit
is ignored.

   [footnote 1: The simple Flush behavior defined by
    EGL_SYNC_FLUSH_COMMANDS_BIT_KHR will not help when waiting for a
    fence command issued in a different context's command stream.
    Applications which block on a fence sync object must take
    additional steps to ensure that the context from which the
    associated fence command was issued has flushed that command to
    the graphics pipeline.]

Errors
------

  * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
    returned and an EGL_BAD_PARAMETER error is generated.
  * If <dpy> does not match the EGLDisplay passed to
    eglCreateSyncKHR when <sync> was created, the behaviour is
    undefined.


The command

    EGLBoolean eglGetSyncAttribKHR(
                        EGLDisplay dpy,
                        EGLSyncKHR sync,
                        EGLint attribute,
                        EGLint *value);

is used to query attributes of the sync object <sync>. Legal values
for <attribute> depend on the type of sync object, as shown in table
3.cc. Assuming no errors are generated, EGL_TRUE is returned and the
value of the queried attribute is returned in <value>.

Attribute              Description                Supported Sync Objects
-----------------      -----------------------    ----------------------
EGL_SYNC_TYPE_KHR      Type of the sync object    All
EGL_SYNC_STATUS_KHR    Status of the sync object  All
EGL_SYNC_CONDITION_KHR Signaling condition        EGL_SYNC_FENCE_KHR only

Table 3.cc  Attributes Accepted by eglGetSyncAttribKHR Command

Errors
------

  * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
    returned and an EGL_BAD_PARAMETER error is generated.
  * If <dpy> does not match the display passed to eglCreateSyncKHR
    when <sync> was created, the behaviour is undefined.
  * If <attribute> is not one of the attributes in table 3.cc,
    EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is
    generated.
  * If <attribute> is not supported for the type of sync object
    passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH
    error is generated.

If any error occurs, <*value> is not modified.

The command

    EGLBoolean eglDestroySyncKHR(
                        EGLDisplay dpy,
                        EGLSyncKHR sync);

is used to destroy an existing sync object.

If any eglClientWaitSyncKHR commands are blocking on <sync> when
eglDestroySyncKHR is called, <sync> is flagged for deletion and will
be deleted when it is no longer associated with any fence command
and is no longer blocking any eglClientWaitSyncKHR command.

If no errors are generated, EGL_TRUE is returned, and <sync> will no
longer be the handle of a valid sync object.

Errors
------

  * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
    returned and an EGL_BAD_PARAMETER error is generated.
  * If <dpy> does not match the display passed to eglCreateSyncKHR
    when <sync> was created, the behaviour is undefined.

Note about the Issues
---------------------
The wording for this extension was originally written as a single
extension defining two types of sync object; a "reusable sync
object" and a "fence sync object". That extension was split to
produce standalone extensions for each type of sync object, and
references to the other type removed from the specification
language. This issues list has been simplied to remove references to
reusable sync objects but is otherwise very similar to the
EGL_KHR_reusable_sync extension issues list.

1. [REMOVED - found in the reusable_sync extension.]

2. [REMOVED - found in the reusable_sync extension.]

3. What does this extension provide that can not be accomplished
with the existing, more efficient eglWaitClient and eglWaitNative
API functions?

RESPONSE: eglWaitClient and eglWaitNative may be implemented in
extremely lightweight manners, in some cases not blocking the
calling thread at all; however, they can not be used to synchronize
between client API contexts and native APIs executing in separate
threads (or simply between client API contexts executing in separate
threads), such as between a thread with an active OpenGL context and
a second thread performing video decode.

4. What does this extension provide that could not be accomplished
with native platform synchronization primitives and the existing
client API Finish commands?

RESPONSE: This extension provides a lighter-weight mechanism for
synchronizing an application with client API command streams than
the all-or-nothing Finish commands, enabling applications to block
until a subset of issued client API commands have completed.

5. [REMOVED - found in the reusable_sync extension.]

6. Please provide a more detailed description of how
eglClientWaitSyncKHR behaves.

RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync
object transitions to the signaled state. Sync object status is
either signaled or unsignaled. More detailed rules describing
signalling follow (these may need to be imbedded into the actual
spec language):

  * A fence sync object has two possible status values: signaled or
    unsignaled.
  * When created, the status of the sync object is unsignaled.
  * A fence command is inserted into a command stream. A fence sync
    object is not.
  * A fence command, once its condition has been met, will set its
    associated sync object to the signaled state. The only condition
    currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR.
  * A wait function, such as ClientWaitSyncKHR, waits on a fence
    sync object, not on a fence command.
  * A wait function called on a sync object in the unsignaled state
    will block. It unblocks (note, not "returns to the application")
    when the sync object transitions to the signaled state.
  * A wait function called on a sync object in the signaled state
    will return immediately.

7. [REMOVED - found in the reusable_sync extension.]

8. [REMOVED - found in the reusable_sync extension.]

9. Should eglDestroySyncKHR release all WaitSyncs placed on a fence
sync object?

RESOLVED: No. (note that this behavior differs from reusable syncs.)

Fence sync objects are intended to be signalled by the graphics
driver within a short period of time (typically less than 1 second
after creation) and so should not cause waiting threads to hang
forever. To reduce implementation complexity, fence sync objects are
defined to not release waiting threads; waiting threads are released
normally when their condition is satisfied or their timeout expires.
The handle to a fence sync object immediately becomes invalid
following a call to eglDestroySyncKHR.