Método IDXGIKeyedMutex::AcquireSync (dxgi.h)

Artículo
08/23/2023

Con una clave, adquiere acceso exclusivo de representación a un recurso compartido.

Sintaxis

HRESULT AcquireSync(
  UINT64 Key,
  DWORD  dwMilliseconds
);

Parámetros

Key

Tipo: UINT64

Valor que indica a qué dispositivo se va a conceder acceso. Este método se realizará correctamente cuando el dispositivo que posee actualmente la superficie llame al método IDXGIKeyedMutex::ReleaseSync con el mismo valor. Este valor puede ser cualquier valor UINT64.

dwMilliseconds

Tipo: DWORD

El intervalo de tiempo de espera en milisegundos. Este método devolverá si transcurre el intervalo y la exclusión mutua con clave no se ha liberado mediante la clave especificada. Si este valor se establece en cero, el método AcquireSync probará para ver si la exclusión mutua con clave se ha liberado y devuelve inmediatamente. Si este valor se establece en INFINITE, el intervalo de tiempo de espera nunca transcurrirá.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente.

Si el dispositivo propietario intentó crear otra exclusión mutua con clave en el mismo recurso compartido, AcquireSync devuelve E_FAIL.

AcquireSync también puede devolver las siguientes constantes DWORD . Por lo tanto, debe comprobar explícitamente estas constantes. Si solo usa la macro SUCCEEDED en el valor devuelto para determinar si AcquireSync se realizó correctamente, no detectará estas constantes.

WAIT_ABANDONED: la superficie compartida y la exclusión mutua con clave ya no están en un estado coherente. Si AcquireSync devuelve este valor, debe liberar y volver a crear la exclusión mutua con clave y la superficie compartida.
WAIT_TIMEOUT: intervalo de tiempo de espera transcurrido antes de que se liberara la clave especificada.

Comentarios

El método AcquireSync crea un bloqueo en una superficie que se comparte entre varios dispositivos, lo que permite que solo un dispositivo se represente en una superficie a la vez.
Este método usa una clave para determinar qué dispositivo tiene actualmente acceso exclusivo a la superficie.

Cuando se crea una superficie con el valor D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX de la enumeración D3D10_RESOURCE_MISC_FLAG , debe llamar al método AcquireSync antes de representarlo en la superficie. Debe llamar al método ReleaseSync cuando haya terminado de representarse en una superficie.

Para adquirir una referencia al objeto de exclusión mutua con claves de un recurso compartido, llame al método QueryInterface del recurso y pase el UUID de la interfaz IDXGIKeyedMutex . Para obtener más información sobre cómo adquirir esta referencia, vea el ejemplo de código siguiente.

El método AcquireSync usa la clave de la siguiente manera, en función del estado de la superficie:

Al crearse inicialmente, la superficie no está en su lugar y cualquier dispositivo puede llamar al método AcquireSync para obtener acceso. En el caso de un dispositivo no propietario, solo se realizará correctamente una clave de 0. Al llamar al método AcquireSync para cualquier otra clave, se detendrá el subproceso de CPU que realiza la llamada.
Si la superficie es propiedad de un dispositivo al llamar al método AcquireSync , el subproceso de CPU que llamó al método AcquireSync se detendrá hasta que el dispositivo propietario llame al método ReleaseSync con la misma clave.
Si la superficie no está instalada al llamar al método AcquireSync (por ejemplo, el último dispositivo propietario ya ha llamado al método ReleaseSync ), el método AcquireSync se realizará correctamente si especifica la misma clave que se especificó cuando se llamó por última vez al método ReleaseSync . Llamar al método AcquireSync con cualquier otra clave provocará un bloqueo.
Cuando el dispositivo propietario llama al método ReleaseSync con una clave determinada y más de un dispositivo está esperando después de llamar al método AcquireSync con la misma clave, cualquiera de los dispositivos en espera se podría reactivar primero. El orden en que se reactivan los dispositivos no está definido.
Una exclusión mutua con clave no admite llamadas recursivas al método AcquireSync .

Ejemplos

Adquisición de una exclusión mutua con claves

En el ejemplo de código siguiente se muestra cómo adquirir un bloqueo en un recurso compartido y cómo especificar una clave al liberarse.


// pDesc has already been set up with texture description.
pDesc.MiscFlags = D3D10_RESOURCE_MISC_SHARED_KEYEDMUTEX;

// Create a shared texture resource.
pD3D10DeviceD->CreateTexture2D(pDesc, NULL, pD3D10Texture);

// Acquire a reference to the keyed mutex.
pD3D10Texture->QueryInterface(_uuidof(IDXGIKeyedMutex), pDXGIKeyedMutex);

// Acquire a lock to the resource.
pDXGIKeyedMutex->AcquireSync(0, INFINITE);

// Release the lock and specify a key.
pDXGIKeyedMutex->ReleaseSync(1);