Fungsi AvRtCreateThreadOrderingGroupExA (avrt.h)

Artikel
02/26/2024

Membuat grup pengurutan utas dan mengaitkan utas server dengan tugas.

Sintaks

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

Parameter

[out] Context

Penunjuk ke handel konteks.

[in] Period

Penunjuk ke nilai, dalam kenaikan 100 nanodetik, yang menentukan periode untuk grup pengurutan utas. Setiap utas dalam grup pemesanan utas berjalan satu kali selama periode ini. Jika semua utas menyelesaikan eksekusinya sebelum periode berakhir, semua utas menunggu hingga sisa periode berlalu sebelum dieksekusi lagi.

Nilai yang mungkin untuk parameter ini bergantung pada platform, tetapi parameter ini bisa serendah 500 mikrosecond atau setingkat 0x1FFFFFFFFFFFFFFF. Jika parameter ini kurang dari 500 mikro detik, maka parameter ini diatur ke 500 mikrosekon. Jika parameter ini lebih besar dari maksimum, maka parameter diatur ke 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

Penunjuk ke pengidentifikasi unik untuk grup pengurutan utas yang akan dibuat. Jika nilai ini tidak unik untuk layanan pemesanan utas, fungsi akan gagal.

Jika pengidentifikasi GUID_NULL pada input, layanan pemesanan utas menghasilkan dan mengembalikan pengidentifikasi unik.

[in, optional] Timeout

Penunjuk ke nilai waktu habis. Semua utas dalam grup harus menyelesaikan eksekusinya dalam Periode plus Batas Waktu.

Jika utas gagal menyelesaikan pemrosesannya dalam periode ditambah interval waktu habis ini, utas akan dihapus dari grup pengurutan utas. Jika induk gagal menyelesaikan pemrosesannya dalam periode ditambah interval waktu habis, grup pengurutan utas akan dihancurkan.

Nilai yang mungkin untuk parameter ini bergantung pada platform, tetapi dapat serendah 500 mikro detik atau setingkat 0x1FFFFFFFFFFFFFFF. Jika parameter ini kurang dari 500 mikro detik, maka parameter ini diatur ke 500 mikrosekon. Jika parameter ini lebih besar dari maksimum, maka parameter diatur ke 0x1FFFFFFFFFFFFFFF.

Jika parameter ini NULL atau 0, defaultnya adalah lima kali nilai Periode.

Jika parameter ini THREAD_ORDER_GROUP_INFINITE_TIMEOUT, grup dibuat dengan interval waktu habis yang tak terbatas. Ini dapat berguna untuk tujuan penelusuran kesalahan.

[in] TaskName

Nama tugas.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika grup pengurutan utas dengan pengidentifikasi yang ditentukan sudah ada, fungsi gagal dan mengatur kesalahan terakhir ke ERROR_ALREADY_EXISTS.

Keterangan

Utas panggilan dianggap sebagai utas induk. Setiap grup pemesanan utas memiliki satu utas induk. Setiap utas induk dapat memiliki nol atau lebih utas pendahulu dan nol atau lebih utas penerus. Utas klien dapat bergabung dengan grup pengurutan utas dan menentukan apakah itu pendahulu atau penerus menggunakan fungsi AvRtJoinThreadOrderingGroup .

Utas induk mencakup kode yang akan dijalankan selama setiap periode dalam perulangan yang dikontrol oleh fungsi AvRtWaitOnThreadOrderingGroup .

Untuk menghapus grup pemesanan utas, panggil fungsi AvRtDeleteThreadOrderingGroup .

Utas dapat membuat lebih dari satu grup pengurutan utas dan bergabung dengan lebih dari satu grup pengurutan utas. Namun, utas tidak dapat bergabung dengan grup pemesanan utas yang sama lebih dari satu kali.

Utas induk dan klien dari grup pemesanan utas berjalan dengan prioritas tinggi. Namun, utas server yang mengelola grup pemesanan utas berjalan pada prioritas normal. Oleh karena itu, mungkin ada peralihan penundaan dari satu utas klien ke utas klien lainnya jika ada utas prioritas tinggi lainnya yang berjalan. Parameter TaskName dari fungsi ini menentukan tugas yang akan dikaitkan dengan utas server.

Contoh

Cuplikan berikut membuat grup pengurutan utas.

#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;
}

Catatan

Header avrt.h mendefinisikan AvRtCreateThreadOrderingGroupEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	avrt.h
Pustaka	Avrt.lib
DLL	Avrt.dll

Lihat juga

Layanan Pemesanan Utas

Bagikan melalui