pub struct Fence { /* private fields */ }Expand description
A two-state synchronization primitive that is signalled by the device and waited on by the host.
Queue-to-host synchronization
The primary use of a fence is to know when execution of a queue has reached a particular point.
When adding a command to a queue, a fence can be provided with the command, to be signaled
when the operation finishes. You can check for a fence’s current status by calling
is_signaled, wait or await on it. If the fence is found to be signaled, that means that
the queue has completed the operation that is associated with the fence, and all operations that
were submitted before it have been completed as well.
When a queue command accesses a resource, it must be kept alive until the queue command has
finished executing, and you may not be allowed to perform certain other operations (or even any)
while the resource is in use. By calling is_signaled, wait or await, the queue will be
notified when the fence is signaled, so that all resources of the associated queue operation and
preceding operations can be released.
Because of this, it is highly recommended to call is_signaled, wait or await on your fences.
Otherwise, the queue will hold onto resources indefinitely (using up memory)
and resource locks will not be released, which may cause errors when submitting future
queue operations. It is not strictly necessary to wait for every fence, as a fence
that was signaled later in the queue will automatically clean up resources associated with
earlier fences too.
Implementations
sourceimpl Fence
impl Fence
sourcepub fn new(
device: Arc<Device>,
create_info: FenceCreateInfo
) -> Result<Fence, FenceError>
pub fn new(
device: Arc<Device>,
create_info: FenceCreateInfo
) -> Result<Fence, FenceError>
Creates a new Fence.
sourcepub fn from_pool(device: Arc<Device>) -> Result<Fence, FenceError>
pub fn from_pool(device: Arc<Device>) -> Result<Fence, FenceError>
Takes a fence from the vulkano-provided fence pool.
If the pool is empty, a new fence will be created.
Upon drop, the fence is put back into the pool.
For most applications, using the fence pool should be preferred, in order to avoid creating new fences every frame.
sourcepub unsafe fn from_handle(
device: Arc<Device>,
handle: Fence,
create_info: FenceCreateInfo
) -> FenceⓘNotable traits for Fenceimpl Future for Fence type Output = Result<(), OomError>;
pub unsafe fn from_handle(
device: Arc<Device>,
handle: Fence,
create_info: FenceCreateInfo
) -> FenceⓘNotable traits for Fenceimpl Future for Fence type Output = Result<(), OomError>;
Creates a new Fence from a raw object handle.
Safety
handlemust be a valid Vulkan object handle created fromdevice.create_infomust match the info used to create the object.
sourcepub fn is_signaled(&self) -> Result<bool, OomError>
pub fn is_signaled(&self) -> Result<bool, OomError>
Returns true if the fence is signaled.
sourcepub fn wait(&self, timeout: Option<Duration>) -> Result<(), FenceError>
pub fn wait(&self, timeout: Option<Duration>) -> Result<(), FenceError>
Waits until the fence is signaled, or at least until the timeout duration has elapsed.
Returns Ok if the fence is now signaled. Returns Err if the timeout was reached instead.
If you pass a duration of 0, then the function will return without blocking.
sourcepub fn multi_wait<'a>(
fences: impl IntoIterator<Item = &'a Fence>,
timeout: Option<Duration>
) -> Result<(), FenceError>
pub fn multi_wait<'a>(
fences: impl IntoIterator<Item = &'a Fence>,
timeout: Option<Duration>
) -> Result<(), FenceError>
sourcepub fn reset(&self) -> Result<(), FenceError>
pub fn reset(&self) -> Result<(), FenceError>
Resets the fence.
The fence must not be in use by a queue operation.
sourcepub fn multi_reset<'a>(
fences: impl IntoIterator<Item = &'a Fence>
) -> Result<(), FenceError>
pub fn multi_reset<'a>(
fences: impl IntoIterator<Item = &'a Fence>
) -> Result<(), FenceError>
Resets multiple fences at once.
The fences must not be in use by a queue operation.
Panics
- Panics if not all fences belong to the same device.
sourcepub fn export_fd(
&self,
handle_type: ExternalFenceHandleType
) -> Result<File, FenceError>
pub fn export_fd(
&self,
handle_type: ExternalFenceHandleType
) -> Result<File, FenceError>
Exports the fence into a POSIX file descriptor. The caller owns the returned File.
The khr_external_fence_fd
extension must be enabled on the device.
sourcepub unsafe fn import_fd(
&self,
import_fence_fd_info: ImportFenceFdInfo
) -> Result<(), FenceError>
pub unsafe fn import_fd(
&self,
import_fence_fd_info: ImportFenceFdInfo
) -> Result<(), FenceError>
Imports a fence from a POSIX file descriptor.
The khr_external_fence_fd
extension must be enabled on the device.
Safety
- If in
import_fence_fd_info,handle_typeisExternalHandleType::OpaqueFd, thenfilemust represent a fence that was exported from Vulkan or a compatible API, with a driver and device UUID equal to those of the device that ownsself.