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;
}
Nota
El encabezado avrt.h define AvRtCreateThreadOrderingGroupEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | avrt.h |
| Library | Avrt.lib |
| Archivo DLL | Avrt.dll |