vulkan-3.6.3: Bindings to the Vulkan graphics API.
Safe HaskellNone
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_deferred_host_operations

Synopsis

Documentation

createDeferredOperationKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device which owns operation.

-> ("allocator" ::: Maybe AllocationCallbacks)

pAllocator controls host memory allocation as described in the Memory Allocation chapter.

-> io DeferredOperationKHR 

vkCreateDeferredOperationKHR - Create a deferred operation handle

Valid Usage (Implicit)

  • device must be a valid Device handle

Return Codes

Success
Failure

See Also

AllocationCallbacks, DeferredOperationKHR, Device

withDeferredOperationKHR :: forall io r. MonadIO io => Device -> Maybe AllocationCallbacks -> (io DeferredOperationKHR -> (DeferredOperationKHR -> io ()) -> r) -> r Source #

A convenience wrapper to make a compatible pair of calls to createDeferredOperationKHR and destroyDeferredOperationKHR

To ensure that destroyDeferredOperationKHR is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass (,) as the first argument.

destroyDeferredOperationKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device which owns operation.

-> DeferredOperationKHR

operation is the completed operation to be destroyed.

-> ("allocator" ::: Maybe AllocationCallbacks)

pAllocator controls host memory allocation as described in the Memory Allocation chapter.

-> io () 

vkDestroyDeferredOperationKHR - Destroy a deferred operation handle

Valid Usage

  • If AllocationCallbacks were provided when operation was created, a compatible set of callbacks must be provided here
  • If no AllocationCallbacks were provided when operation was created, pAllocator must be NULL
  • operation must be completed

Valid Usage (Implicit)

  • device must be a valid Device handle
  • If operation is not NULL_HANDLE, operation must be a valid DeferredOperationKHR handle
  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
  • If operation is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to operation must be externally synchronized

See Also

AllocationCallbacks, DeferredOperationKHR, Device

getDeferredOperationMaxConcurrencyKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device which owns operation.

device must be a valid Device handle

-> DeferredOperationKHR

operation is the deferred operation to be queried.

operation must be a valid DeferredOperationKHR handle

operation must have been created, allocated, or retrieved from device

-> io Word32 

vkGetDeferredOperationMaxConcurrencyKHR - Query the maximum concurrency on a deferred operation

Description

The returned value is the maximum number of threads that can usefully execute a deferred operation concurrently, reported for the state of the deferred operation at the point this command is called. This value is intended to be used to better schedule work onto available threads. Applications can join any number of threads to the deferred operation and expect it to eventually complete, though excessive joins may return THREAD_DONE_KHR immediately, performing no useful work.

If operation is complete, getDeferredOperationMaxConcurrencyKHR returns zero.

If operation is currently joined to any threads, the value returned by this command may immediately be out of date.

If operation is pending, implementations must not return zero unless at least one thread is currently executing deferredOperationJoinKHR on operation. If there are such threads, the implementation should return an estimate of the number of additional threads which it could profitably use.

Implementations may return 232-1 to indicate that the maximum concurrency is unknown and cannot be easily derived. Implementations may return values larger than the maximum concurrency available on the host CPU. In these situations, an application should clamp the return value rather than oversubscribing the machine.

Note

The recommended usage pattern for applications is to query this value once, after deferral, and schedule no more than the specified number of threads to join the operation. Each time a joined thread receives THREAD_IDLE_KHR, the application should schedule an additional join at some point in the future, but is not required to do so.

Valid Usage (Implicit)

See Also

DeferredOperationKHR, Device

getDeferredOperationResultKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device which owns operation.

device must be a valid Device handle

-> DeferredOperationKHR

operation is the operation whose deferred result is being queried.

operation must be a valid DeferredOperationKHR handle

operation must have been created, allocated, or retrieved from device

-> io Result 

vkGetDeferredOperationResultKHR - Query the result of a deferred operation

Description

If the deferred operation is pending, getDeferredOperationResultKHR returns NOT_READY.

If no command has been deferred on operation, getDeferredOperationResultKHR returns SUCCESS.

Otherwise, it returns the result of the previous deferred operation. This value must be one of the Result values which could have been returned by the original command if the operation had not been deferred.

Return Codes

Success

See Also

DeferredOperationKHR, Device

deferredOperationJoinKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device which owns operation.

-> DeferredOperationKHR

operation is the deferred operation that the calling thread should work on.

-> io Result 

vkDeferredOperationJoinKHR - Assign a thread to a deferred operation

Description

The deferredOperationJoinKHR command will execute a portion of the deferred operation on the calling thread.

The return value will be one of the following:

  • A return value of SUCCESS indicates that operation is complete. The application should use getDeferredOperationResultKHR to retrieve the result of operation.
  • A return value of THREAD_DONE_KHR indicates that the deferred operation is not complete, but there is no work remaining to assign to threads. Future calls to deferredOperationJoinKHR are not necessary and will simply harm performance. This situation may occur when other threads executing deferredOperationJoinKHR are about to complete operation, and the implementation is unable to partition the workload any further.
  • A return value of THREAD_IDLE_KHR indicates that the deferred operation is not complete, and there is no work for the thread to do at the time of the call. This situation may occur if the operation encounters a temporary reduction in parallelism. By returning THREAD_IDLE_KHR, the implementation is signaling that it expects that more opportunities for parallelism will emerge as execution progresses, and that future calls to deferredOperationJoinKHR can be beneficial. In the meantime, the application can perform other work on the calling thread.

Implementations must guarantee forward progress by enforcing the following invariants:

  1. If only one thread has invoked deferredOperationJoinKHR on a given operation, that thread must execute the operation to completion and return SUCCESS.
  2. If multiple threads have concurrently invoked deferredOperationJoinKHR on the same operation, then at least one of them must complete the operation and return SUCCESS.

Valid Usage (Implicit)

  • device must be a valid Device handle
  • operation must be a valid DeferredOperationKHR handle
  • operation must have been created, allocated, or retrieved from device

Return Codes

Success
Failure

See Also

DeferredOperationKHR, Device

data DeferredOperationInfoKHR Source #

VkDeferredOperationInfoKHR - Deferred operation request

Description

The application can request deferral of an operation by adding this structure to the argument list of a command or by providing this in the pNext chain of a relevant structure for an operation when the corresponding command is invoked. If this structure is not present, no deferral is requested. If operationHandle is NULL_HANDLE, no deferral is requested and the command proceeds as if no DeferredOperationInfoKHR structure was provided.

When an application requests an operation deferral, the implementation may defer the operation. When deferral is requested and the implementation defers any operation, the implementation must return OPERATION_DEFERRED_KHR as the success code if no errors occurred. When deferral is requested, the implementation should defer the operation when the workload is significant, however if the implementation chooses not to defer any of the requested operations and instead executes all of them immediately, the implementation must return OPERATION_NOT_DEFERRED_KHR as the success code if no errors occurred.

A deferred operation is created complete with an initial result value of SUCCESS. The deferred operation becomes pending when an operation has been successfully deferred with that operationHandle.

A deferred operation is considered pending until the deferred operation completes. A pending deferred operation becomes complete when it has been fully executed by one or more threads. Pending deferred operations will never complete until they are joined by an application thread, using deferredOperationJoinKHR. Applications can join multiple threads to the same deferred operation, enabling concurrent execution of subtasks within that operation.

The application can query the status of a DeferredOperationKHR using the getDeferredOperationMaxConcurrencyKHR or getDeferredOperationResultKHR commands.

From the perspective of other commands - parameters to the original command that are externally synchronized must not be accessed before the deferred operation completes, and the result of the deferred operation (e.g. object creation) are not considered complete until the deferred operation completes.

If the deferred operation is one which creates an object (for example, a pipeline object), the implementation must allocate that object as it normally would, and return a valid handle to the application. This object is a pending object, and must not be used by the application until the deferred operation is completed (unless otherwise specified by the deferral extension). When the deferred operation is complete, the application should call getDeferredOperationResultKHR to obtain the result of the operation. If getDeferredOperationResultKHR indicates failure, the application must destroy the pending object using an appropriate command, so that the implementation has an opportunity to recover the handle. The application must not perform this destruction until the deferred operation is complete. Construction of the pending object uses the same allocator which would have been used if the operation had not been deferred.

Valid Usage

  • Any previous deferred operation that was associated with operationHandle must be complete

Valid Usage (Implicit)

See Also

DeferredOperationKHR, StructureType

Constructors

DeferredOperationInfoKHR 

Fields

Instances

Instances details
Eq DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

Show DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

Generic DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

Associated Types

type Rep DeferredOperationInfoKHR :: Type -> Type #

Storable DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

FromCStruct DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

ToCStruct DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

Zero DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

type Rep DeferredOperationInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_deferred_host_operations

type Rep DeferredOperationInfoKHR = D1 ('MetaData "DeferredOperationInfoKHR" "Vulkan.Extensions.VK_KHR_deferred_host_operations" "vulkan-3.6.3-inplace" 'False) (C1 ('MetaCons "DeferredOperationInfoKHR" 'PrefixI 'True) (S1 ('MetaSel ('Just "operationHandle") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 DeferredOperationKHR)))

type KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME = "VK_KHR_deferred_host_operations" Source #

newtype DeferredOperationKHR Source #

VkDeferredOperationKHR - A deferred operation

Description

This handle refers to a tracking structure which manages the execution state for a deferred command.

See Also

DeferredOperationInfoKHR, createDeferredOperationKHR, deferredOperationJoinKHR, destroyDeferredOperationKHR, getDeferredOperationMaxConcurrencyKHR, getDeferredOperationResultKHR

Instances

Instances details
Eq DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Ord DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Show DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Storable DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Zero DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

HasObjectType DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

IsHandle DeferredOperationKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles