Added in API level 33

SyncFence


class SyncFence : AutoCloseable, Parcelable
kotlin.Any
   ↳ android.hardware.SyncFence

A SyncFence represents a synchronization primitive which signals when hardware units have completed work on a particular resource. They initially start in an unsignaled state and make a one-time transition to either a signaled or error state. SyncFences are created by various device APIs in response to submitting tasks to the device. They cannot be created nor signaled by userspace. As a result, this means that a SyncFence will make always make forward progress.

SyncFence's generally come in one of two varieties. "Presentation fences" refer to a SyncFence when the writing to a buffer has finished. "Release fences" then refer to when the reading from a buffer has finished.

For example, a GPU rendering to a framebuffer may generate a synchronization fence, e.g., an EGLSync or VkFence, which signals when rendering has completed. Once the fence signals, then the backing storage for the framebuffer may be safely read from, such as for display or for media encoding. This would be referred to as a "presentation fence."

Similarly when using an android.media.ImageWriter it is possible that an android.media.Image returned by ImageWriter#dequeueInputImage() may already have a fence set on it. This would be what is referred to as either a "release fence" or an "acqurie fence" and indicates the fence that the writer must wait on before writing to the underlying buffer. In the case of ImageWriter this is done automatically when eg Image#getPlanes() is called, however when using Image#getHardwareBuffer() it is the caller's responsibility to ensure the release fence has signaled before writing to the buffer.

Summary

Constants
static Long

An invalid signal time.

static Long

A pending signal time.

Inherited constants
Public constructors

Creates a copy of the SyncFence from an existing one.

Public methods
Boolean
await(timeout: Duration)

Waits for a SyncFence to signal for up to the timeout duration.

Boolean

Waits forever for a SyncFence to signal.

Unit

Close the SyncFence.

Int

Long

Returns the time in nanoseconds that the fence signaled in the CLOCK_MONOTONIC time domain.

Boolean

Checks if the SyncFile object is valid.

Unit
writeToParcel(out: Parcel, flags: Int)

Flatten this object into a Parcel.

Properties
static Parcelable.Creator<SyncFence!>

Constants

SIGNAL_TIME_INVALID

Added in API level 33
static val SIGNAL_TIME_INVALID: Long

An invalid signal time. Represents either the signal time for a SyncFence that isn't valid (that is, isValid() is false), or if an error occurred while attempting to retrieve the signal time.

Value: -1L

SIGNAL_TIME_PENDING

Added in API level 33
static val SIGNAL_TIME_PENDING: Long

A pending signal time. This is equivalent to the max value of a long, representing an infinitely far point in the future.

Value: 9223372036854775807L

Public constructors

SyncFence

Added in API level 35
SyncFence(other: SyncFence)

Creates a copy of the SyncFence from an existing one. Both fences must be closed() independently.

Parameters
other SyncFence: This value cannot be null.

Public methods

await

Added in API level 33
fun await(timeout: Duration): Boolean

Waits for a SyncFence to signal for up to the timeout duration. An invalid SyncFence, that is if isValid() is false, is treated equivalently to a SyncFence that has already signaled. That is, wait() will immediately return true.

Parameters
timeout Duration: The timeout duration. If the duration is negative, then this waits forever. This value cannot be null.
Return
Boolean true if the fence signaled or isn't valid, false otherwise.

awaitForever

Added in API level 33
fun awaitForever(): Boolean

Waits forever for a SyncFence to signal. An invalid SyncFence, that is if isValid() is false, is treated equivalently to a SyncFence that has already signaled. That is, wait() will immediately return true.

Return
Boolean true if the fence signaled or isn't valid, false otherwise.

close

Added in API level 33
fun close(): Unit

Close the SyncFence. This implementation closes the underlying OS resources allocated this stream.

Exceptions
java.lang.Exception if this resource cannot be closed

describeContents

Added in API level 33
fun describeContents(): Int
Return
Int a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR

getSignalTime

Added in API level 33
fun getSignalTime(): Long

Returns the time in nanoseconds that the fence signaled in the CLOCK_MONOTONIC time domain. This corresponds to System#nanoTime() but may also be compared to SystemClock#uptimeMillis() after adjusting for milliseconds vs. nanoseconds. If the fence isn't valid, that is if isValid() is false, then this returns SIGNAL_TIME_INVALID. Similarly, if an error occurs while trying to access the signal time, then SIGNAL_TIME_INVALID is also returned. If the fence hasn't yet signaled, then SIGNAL_TIME_PENDING is returned.

Return
Long The time the fence signaled, SIGNAL_TIME_INVALID if there's an error, or SIGNAL_TIME_PENDING if the fence hasn't signaled yet.

isValid

Added in API level 33
fun isValid(): Boolean

Checks if the SyncFile object is valid.

Return
Boolean true if the file descriptor represents a valid, open file; false otherwise.

writeToParcel

Added in API level 33
fun writeToParcel(
    out: Parcel,
    flags: Int
): Unit

Flatten this object into a Parcel.

Parameters
dest The Parcel in which the object should be written. This value cannot be null.
flags Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE
out Parcel: The Parcel in which the object should be written. This value cannot be null.

Properties

CREATOR

Added in API level 33
static val CREATOR: Parcelable.Creator<SyncFence!>