Función AvRtCreateThreadOrderingGroupExA (avrt.h)

Crea un grupo de ordenación de subprocesos y asocia el subproceso de servidor a una tarea.

Sintaxis

AVRTAPI BOOL AvRtCreateThreadOrderingGroupExA(
  [out]          PHANDLE        Context,
  [in]           PLARGE_INTEGER Period,
  [in, out]      GUID           *ThreadOrderingGuid,
  [in, optional] PLARGE_INTEGER Timeout,
  [in]           LPCSTR         TaskName
);

Parámetros

[out] Context

Puntero a un identificador de contexto.

[in] Period

Puntero a un valor, en incrementos de 100 nanosegundos, que especifica el período para el grupo de ordenación de subprocesos. Cada subproceso del grupo de ordenación de subprocesos se ejecuta una vez durante este período. Si todos los subprocesos completan su ejecución antes de que finalice un período, todos los subprocesos esperan hasta que transcurre el resto del período antes de que se vuelva a ejecutar.

Los valores posibles para este parámetro dependen de la plataforma, pero este parámetro puede ser tan bajo como 500 microsegundos o tan alto como 0x1FFFFFFFFFFFFFFF. Si este parámetro es menor que 500 microsegundos, se establece en 500 microsegundos. Si este parámetro es mayor que el máximo, se establece en 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

Puntero al identificador único del grupo de ordenación de subprocesos que se va a crear. Si este valor no es único para el servicio de ordenación de subprocesos, se produce un error en la función.

Si el identificador se GUID_NULL en la entrada, el servicio de ordenación de subprocesos genera y devuelve un identificador único.

[in, optional] Timeout

Puntero a un valor de tiempo de espera. Todos los subprocesos del grupo deben completar su ejecución en Período más Tiempo de espera.

Si un subproceso no puede completar su procesamiento dentro del período más este intervalo de tiempo de espera, se quita del grupo de ordenación de subprocesos. Si el elemento primario no puede completar su procesamiento dentro del período más el intervalo de tiempo de espera, se destruye el grupo de ordenación de subprocesos.

Los valores posibles de este parámetro dependen de la plataforma, pero pueden ser tan bajos como 500 microsegundos o tan altos como 0x1FFFFFFFFFFFFFFF. Si este parámetro es menor que 500 microsegundos, se establece en 500 microsegundos. Si este parámetro es mayor que el máximo, se establece en 0x1FFFFFFFFFFFFFFF.

Si este parámetro es NULL o 0, el valor predeterminado es cinco veces el valor de Period.

Si este parámetro es THREAD_ORDER_GROUP_INFINITE_TIMEOUT, el grupo se crea con un intervalo de tiempo de espera infinito. Esto puede ser útil para fines de depuración.

[in] TaskName

Nombre de la tarea.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si ya existe un grupo de ordenación de subprocesos con el identificador especificado, se produce un error en la función y se establece el último error en ERROR_ALREADY_EXISTS.

Comentarios

El subproceso que realiza la llamada se considera el subproceso primario. Cada grupo de ordenación de subprocesos tiene un subproceso primario. Cada subproceso primario puede tener cero o más subprocesos predecesores y cero o más subprocesos sucesores. Un subproceso de cliente puede unirse a un grupo de ordenación de subprocesos y especificar si es predecesor o sucesor mediante la función AvRtJoinThreadOrderingGroup .

El subproceso primario incluye el código que se va a ejecutar durante cada período dentro de un bucle controlado por la función AvRtWaitOnThreadOrderingGroup .

Para eliminar el grupo de ordenación de subprocesos, llame a la función AvRtDeleteThreadOrderingGroup .

Un subproceso puede crear más de un grupo de ordenación de subprocesos y unirse a más de un grupo de ordenación de subprocesos. Sin embargo, un subproceso no puede unirse al mismo grupo de ordenación de subprocesos más de una vez.

Los subprocesos primarios y de cliente de un grupo de ordenación de subprocesos se ejecutan en prioridades elevadas. Sin embargo, el subproceso de servidor que administra el grupo de ordenación de subprocesos se ejecuta con prioridad normal. Por lo tanto, puede haber un retraso al cambiar de un subproceso de cliente a otro si hay otros subprocesos de prioridad alta en ejecución. El parámetro TaskName de esta función especifica la tarea que se va a asociar al subproceso del servidor.

Ejemplos

El fragmento de código siguiente crea un grupo de ordenación de subprocesos.

#include <windows.h>
#include <avrt.h>
#include <stdio.h>

#pragma comment(lib, "Avrt.lib")

#define _100NS_IN_1MS 10000

int main( void )
{
    HANDLE hContext = NULL;
    LARGE_INTEGER period, timeout;
    GUID guid = { 0 };
    BOOL bRes;

    period.QuadPart = Int32x32To64(_100NS_IN_1MS, 1000);   // 1 second
    timeout.QuadPart = Int32x32To64(_100NS_IN_1MS, 10000); // 10 seconds

    bRes = AvRtCreateThreadOrderingGroupEx( 
            &hContext,
            &period,
            &guid,
            &timeout,
            TEXT("Audio") );

    if( bRes != TRUE )
    {
        printf("Error creating group (%d)\n", GetLastError());
            return 1;
    }

    return 0;
}

Requisitos

Consulte también

Servicio de ordenación de subprocesos