Package org.lwjgl.vulkan

Class KHRDeferredHostOperations

  • public class KHRDeferredHostOperations
extends java.lang.Object
    The VK_KHR_deferred_host_operations extension defines the infrastructure and usage patterns for deferrable commands, but does not specify any commands as deferrable. This is left to additional dependent extensions. Commands must not be deferred unless the deferral is specifically allowed by another extension which depends on VK_KHR_deferred_host_operations.
    Code Examples

    The following examples will illustrate the concept of deferrable operations using a hypothetical example. The command vkDoSomethingExpensiveEXT denotes a deferrable command. The structure stext:VkExpensiveOperationArgsEXT represents the arguments which it would normally accept.

    The following example illustrates how a vulkan application might request deferral of an expensive operation:

    
 // create a deferred operation
 VkDeferredOperationKHR hOp;
 VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
 assert(result == VK_SUCCESS);
 
 result = vkDoSomethingExpensive(device, hOp, ...);
 assert( result == VK_OPERATION_DEFERRED_KHR );
 
 // operation was deferred.  Execute it asynchronously
 std::async::launch(
     [ hOp ] ( )
     {
         vkDeferredOperationJoinKHR(device, hOp);
 
         result = vkGetDeferredOperationResultKHR(device, hOp);
 
         // deferred operation is now complete.  'result' indicates success or failure
 
         vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
     }
 );

    The following example illustrates extracting concurrency from a single deferred operation:

    
 // create a deferred operation
 VkDeferredOperationKHR hOp;
 VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
 assert(result == VK_SUCCESS);
 
 result = vkDoSomethingExpensive(device, hOp, ...);
 assert( result == VK_OPERATION_DEFERRED_KHR );
 
 // Query the maximum amount of concurrency and clamp to the desired maximum
 uint32_t numLaunches = std::min(vkGetDeferredOperationMaxConcurrencyKHR(device, hOp), maxThreads);
 
 std::vector<std::future<void> > joins;
 
 for (uint32_t i = 0; i < numLaunches; i++) {
   joins.emplace_back(std::async::launch(
     [ hOp ] ( )
     {
         vkDeferredOperationJoinKHR(device, hOp);
                 // in a job system, a return of VK_THREAD_IDLE_KHR should queue another
                 // job, but it is not functionally required
     }
   );
 }
 
 for (auto &f : joins) {
   f.get();
 }
 
 result = vkGetDeferredOperationResultKHR(device, hOp);
 
 // deferred operation is now complete.  'result' indicates success or failure
 
 vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);

    The following example shows a subroutine which guarantees completion of a deferred operation, in the presence of multiple worker threads, and returns the result of the operation.

    
 VkResult FinishDeferredOperation(VkDeferredOperationKHR hOp)
 {
     // Attempt to join the operation until the implementation indicates that we should stop
 
     VkResult result = vkDeferredOperationJoinKHR(device, hOp);
     while( result == VK_THREAD_IDLE_KHR )
     {
         std::this_thread::yield();
         result = vkDeferredOperationJoinKHR(device, hOp);
     }
 
     switch( result )
     {
     case VK_SUCCESS:
         {
             // deferred operation has finished.  Query its result
             result = vkGetDeferredOperationResultKHR(device, hOp);
         }
         break;
 
     case VK_THREAD_DONE_KHR:
         {
             // deferred operation is being wrapped up by another thread
             //  wait for that thread to finish
             do
             {
                 std::this_thread::yield();
                 result = vkGetDeferredOperationResultKHR(device, hOp);
             } while( result == VK_NOT_READY );
         }
         break;
 
     default:
         assert(false); // other conditions are illegal.
         break;
     }
 
     return result;
 }
    VK_KHR_deferred_host_operations
    Name String
    VK_KHR_deferred_host_operations
    Extension Type
    Device extension
    Registered Extension Number
    269
    Revision
    4
    Extension and Version Dependencies
    • Requires Vulkan 1.0
    Contact
    Other Extension Metadata
    Last Modified Date
    2020-11-12
    IP Status
    No known IP claims.
    Contributors
    • Joshua Barczak, Intel
    • Jeff Bolz, NVIDIA
    • Daniel Koch, NVIDIA
    • Slawek Grajewski, Intel
    • Tobias Hector, AMD
    • Yuriy O’Donnell, Epic
    • Eric Werness, NVIDIA
    • Baldur Karlsson, Valve
    • Jesse Barker, Unity
    • Contributors to VK_KHR_acceleration_structure, VK_KHR_ray_tracing_pipeline

    • Method Detail

      • nvkCreateDeferredOperationKHR

        public static int nvkCreateDeferredOperationKHR​(org.lwjgl.vulkan.VkDevice device,
                                                long pAllocator,
                                                long pDeferredOperation)
        Unsafe version of: CreateDeferredOperationKHR

      • vkCreateDeferredOperationKHR

        public static int vkCreateDeferredOperationKHR​(org.lwjgl.vulkan.VkDevice device,
                                               @Nullable
                                               VkAllocationCallbacks pAllocator,
                                               java.nio.LongBuffer pDeferredOperation)
        Create a deferred operation handle.
        C Specification

        To construct the tracking object for a deferred command, call:

        
 VkResult vkCreateDeferredOperationKHR(
     VkDevice                                    device,
     const VkAllocationCallbacks*                pAllocator,
     VkDeferredOperationKHR*                     pDeferredOperation);
        Valid Usage (Implicit)
        • device must be a valid VkDevice handle
        • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
        • pDeferredOperation must be a valid pointer to a VkDeferredOperationKHR handle
        Return Codes
        On success, this command returns
        On failure, this command returns
        See Also

        VkAllocationCallbacks

        Parameters:
        device - the device which owns operation.
        pAllocator - controls host memory allocation as described in the Memory Allocation chapter.
        pDeferredOperation - a pointer to a handle in which the created VkDeferredOperationKHR is returned.

      • nvkDestroyDeferredOperationKHR

        public static void nvkDestroyDeferredOperationKHR​(org.lwjgl.vulkan.VkDevice device,
                                                  long operation,
                                                  long pAllocator)
        Unsafe version of: DestroyDeferredOperationKHR

      • vkDestroyDeferredOperationKHR

        public static void vkDestroyDeferredOperationKHR​(org.lwjgl.vulkan.VkDevice device,
                                                 long operation,
                                                 @Nullable
                                                 VkAllocationCallbacks pAllocator)
        Destroy a deferred operation handle.
        C Specification

        When a deferred operation is completed, the application can destroy the tracking object by calling:

        
 void vkDestroyDeferredOperationKHR(
     VkDevice                                    device,
     VkDeferredOperationKHR                      operation,
     const VkAllocationCallbacks*                pAllocator);
        Valid Usage
        • If VkAllocationCallbacks were provided when operation was created, a compatible set of callbacks must be provided here
        • If no VkAllocationCallbacks were provided when operation was created, pAllocator must be NULL
        • operation must be completed
        Valid Usage (Implicit)
        • device must be a valid VkDevice handle
        • If operation is not NULL_HANDLE, operation must be a valid VkDeferredOperationKHR handle
        • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks 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

        VkAllocationCallbacks

        Parameters:
        device - the device which owns operation.
        operation - the completed operation to be destroyed.
        pAllocator - controls host memory allocation as described in the Memory Allocation chapter.

      • vkGetDeferredOperationMaxConcurrencyKHR

        public static int vkGetDeferredOperationMaxConcurrencyKHR​(org.lwjgl.vulkan.VkDevice device,
                                                          long operation)
        Query the maximum concurrency on a deferred operation.
        C Specification

        To query the number of additional threads that can usefully be joined to a deferred operation, call:

        
 uint32_t vkGetDeferredOperationMaxConcurrencyKHR(
     VkDevice                                    device,
     VkDeferredOperationKHR                      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, vkGetDeferredOperationMaxConcurrencyKHR 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)
        • device must be a valid VkDevice handle
        • operation must be a valid VkDeferredOperationKHR handle
        • operation must have been created, allocated, or retrieved from device
        Parameters:
        device - the device which owns operation.
        operation - the deferred operation to be queried.

      • vkGetDeferredOperationResultKHR

        public static int vkGetDeferredOperationResultKHR​(org.lwjgl.vulkan.VkDevice device,
                                                  long operation)
        Query the result of a deferred operation.
        C Specification

        The vkGetDeferredOperationResultKHR function is defined as:

        
 VkResult vkGetDeferredOperationResultKHR(
     VkDevice                                    device,
     VkDeferredOperationKHR                      operation);
        Description

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

        If the deferred operation is pending, vkGetDeferredOperationResultKHR returns NOT_READY.

        If the deferred operation is complete, it returns the appropriate return value from the original command. This value must be one of the VkResult values which could have been returned by the original command if the operation had not been deferred.

        Valid Usage (Implicit)
        • device must be a valid VkDevice handle
        • operation must be a valid VkDeferredOperationKHR handle
        • operation must have been created, allocated, or retrieved from device
        Return Codes
        On success, this command returns
        Parameters:
        device - the device which owns operation.
        operation - the operation whose deferred result is being queried.

      • vkDeferredOperationJoinKHR

        public static int vkDeferredOperationJoinKHR​(org.lwjgl.vulkan.VkDevice device,
                                             long operation)
        Assign a thread to a deferred operation.
        C Specification

        To assign a thread to a deferred operation, call:

        
 VkResult vkDeferredOperationJoinKHR(
     VkDevice                                    device,
     VkDeferredOperationKHR                      operation);
        Description

        The vkDeferredOperationJoinKHR 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:

        • If only one thread has invoked DeferredOperationJoinKHR on a given operation, that thread must execute the operation to completion and return SUCCESS.
        • 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 VkDevice handle
        • operation must be a valid VkDeferredOperationKHR handle
        • operation must have been created, allocated, or retrieved from device
        Return Codes
        On success, this command returns
        On failure, this command returns
        Parameters:
        device - the device which owns operation.
        operation - the deferred operation that the calling thread should work on.

      • vkCreateDeferredOperationKHR

        public static int vkCreateDeferredOperationKHR​(org.lwjgl.vulkan.VkDevice device,
                                               @Nullable
                                               VkAllocationCallbacks pAllocator,
                                               long[] pDeferredOperation)
        Array version of: CreateDeferredOperationKHR