Top Description Fields Constructors Methods
org.lwjgl.vulkan

public Class KHRDeferredHostOperations

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.system.*
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 vkDoSomethingExpensive denotes a deferrable command.

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
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

Field Summary

Modifier and TypeField and Description
public static final String
VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME

The extension name.

public static final int
VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSION

The extension specification version.

public static final int
VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR

Extends VkObjectType.

public static final int
VK_OPERATION_DEFERRED_KHR

Extends VkResult.

public static final int
VK_OPERATION_NOT_DEFERRED_KHR

Extends VkResult.

public static final int
VK_THREAD_DONE_KHR

Extends VkResult.

public static final int
VK_THREAD_IDLE_KHR

Extends VkResult.

Constructor Summary

AccessConstructor and Description
protected
KHRDeferredHostOperations()

Method Summary

Modifier and TypeMethod and Description
public static int
nvkCreateDeferredOperationKHR(VkDevice device, long pAllocator, long pDeferredOperation)

Unsafe version of: CreateDeferredOperationKHR

public static void
nvkDestroyDeferredOperationKHR(VkDevice device, long operation, long pAllocator)

Unsafe version of: DestroyDeferredOperationKHR

public static int
vkCreateDeferredOperationKHR(VkDevice
the device which owns operation.
device, VkAllocationCallbacks
controls host memory allocation as described in the Memory Allocation chapter.
pAllocator, LongBuffer
a pointer to a handle in which the created VkDeferredOperationKHR is returned.
pDeferredOperation)

Create a deferred operation handle.

public static int
vkCreateDeferredOperationKHR(VkDevice device, VkAllocationCallbacks pAllocator, long[] pDeferredOperation)

Array version of: CreateDeferredOperationKHR

public static int
vkDeferredOperationJoinKHR(VkDevice
the device which owns operation.
device, long
the deferred operation that the calling thread should work on.
operation)

Assign a thread to a deferred operation.

public static void
vkDestroyDeferredOperationKHR(VkDevice
the device which owns operation.
device, long
the completed operation to be destroyed.
operation, VkAllocationCallbacks
controls host memory allocation as described in the Memory Allocation chapter.
pAllocator)

Destroy a deferred operation handle.

public static int
vkGetDeferredOperationMaxConcurrencyKHR(VkDevice
the device which owns operation.
device, long
the deferred operation to be queried.
operation)

Query the maximum concurrency on a deferred operation.

public static int
vkGetDeferredOperationResultKHR(VkDevice
the device which owns operation.
device, long
the operation whose deferred result is being queried.
operation)

Query the result of a deferred operation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAMEback to summary
public static final String VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME

The extension name.

VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSIONback to summary
public static final int VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSION

The extension specification version.

VK_OBJECT_TYPE_DEFERRED_OPERATION_KHRback to summary
public static final int VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR

Extends VkObjectType.

VK_OPERATION_DEFERRED_KHRback to summary
public static final int VK_OPERATION_DEFERRED_KHR

Extends VkResult.

Enum values:
VK_OPERATION_NOT_DEFERRED_KHRback to summary
public static final int VK_OPERATION_NOT_DEFERRED_KHR

Extends VkResult.

Enum values:
VK_THREAD_DONE_KHRback to summary
public static final int VK_THREAD_DONE_KHR

Extends VkResult.

Enum values:
VK_THREAD_IDLE_KHRback to summary
public static final int VK_THREAD_IDLE_KHR

Extends VkResult.

Enum values:

Constructor Detail

KHRDeferredHostOperationsback to summary
protected KHRDeferredHostOperations()

Method Detail

nvkCreateDeferredOperationKHRback to summary
public static int nvkCreateDeferredOperationKHR(VkDevice device, long pAllocator, long pDeferredOperation)

Unsafe version of: CreateDeferredOperationKHR

nvkDestroyDeferredOperationKHRback to summary
public static void nvkDestroyDeferredOperationKHR(VkDevice device, long operation, long pAllocator)

Unsafe version of: DestroyDeferredOperationKHR

vkCreateDeferredOperationKHRback to summary
public static int vkCreateDeferredOperationKHR(VkDevice device, VkAllocationCallbacks pAllocator, 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:VkDevice

the device which owns operation.

pAllocator:VkAllocationCallbacks

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

pDeferredOperation:LongBuffer

a pointer to a handle in which the created VkDeferredOperationKHR is returned.

Annotations
@NativeType:VkResult
vkCreateDeferredOperationKHRback to summary
public static int vkCreateDeferredOperationKHR(VkDevice device, VkAllocationCallbacks pAllocator, long[] pDeferredOperation)

Array version of: CreateDeferredOperationKHR

Annotations
@NativeType:VkResult
vkDeferredOperationJoinKHRback to summary
public static int vkDeferredOperationJoinKHR(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:VkDevice

the device which owns operation.

operation:long

the deferred operation that the calling thread should work on.

Annotations
@NativeType:VkResult
vkDestroyDeferredOperationKHRback to summary
public static void vkDestroyDeferredOperationKHR(VkDevice device, long operation, 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:VkDevice

the device which owns operation.

operation:long

the completed operation to be destroyed.

pAllocator:VkAllocationCallbacks

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

vkGetDeferredOperationMaxConcurrencyKHRback to summary
public static int vkGetDeferredOperationMaxConcurrencyKHR(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:VkDevice

the device which owns operation.

operation:long

the deferred operation to be queried.

Annotations
@NativeType:uint32_t
vkGetDeferredOperationResultKHRback to summary
public static int vkGetDeferredOperationResultKHR(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:VkDevice

the device which owns operation.

operation:long

the operation whose deferred result is being queried.

Annotations
@NativeType:VkResult