Developing with the Thread Ordering Service

Article
10/15/2014

This article describes the new Thread Ordering Service and thread ordering groups in Windows Server® 2008. A discussion on thread ordering concepts can be found in the companion topic Understanding the Thread Ordering Service.

Thread Ordering APIs

Thread ordering groups are used to ensure that the Thread Ordering Service executes a collection of threads in a specific order and within a specified time interval. Each thread ordering group has a parent thread and zero or more client threads. To use the thread ordering APIs discussed in this article, make sure that the Thread Ordering Service is running. This service is not started by default.

A thread becomes the parent thread by creating a thread ordering group. A parent thread creates a group by calling the AvRtCreateThreadOrderingGroup function. The caller specifies the time period within which the service must execute all threads in the group, and a timeout value. The total amount of time within which all threads in the group must complete execution is the time period plus the timeout. The caller can specify a Globally Unique Identifier (GUID) that group members use to identify the group. If the caller does not provide a GUID, the Thread Ordering Service generates a new GUID, which the function returns to the caller. The function also returns an opaque handle that is required by other thread ordering group APIs.

After the thread ordering group has been created, client threads join the group by calling the AvRtJoinThreadOrderingGroup. The calling thread specifies whether it should be scheduled for execution before or after the parent thread. Client threads are scheduled either before or after the parent, which they specify when joining the group, and then in the order in which they joined the group.

The parent and client threads enclose the code to be executed during each time period within a loop that is controlled by the AvRtWaitOnThreadOrderingGroup function. This function blocks a calling thread until the Thread Ordering Service selects the thread for execution. If the thread ordering group is deleted or the calling thread did not complete its processing within the previous time period, this function will return an error.

Client threads can leave a group at any time by calling the AvRtLeaveThreadOrderingGroup function. A parent thread should not leave its group. When the group is no longer needed, the parent thread deletes the group by calling the AvRtDeleteThreadOrderingGroup function. Once this function is called, any client threads in the group will receive an error the next time they call the AvRtWaitOnThreadOrderingGroup function.

Thread Ordering Examples

The examples in this section demonstrate performing thread ordering tasks. Tasks are organized by role (parent thread versus client threads).

Parent Thread Tasks

The examples in this section demonstrate performing the following tasks:

Creating a thread ordering group
Executing code as a member of a thread ordering group
Deleting a thread ordering group

Creating a Thread Ordering Group

The following code example demonstrates using the AvRtCreateThreadOrderingGroup function to create a thread ordering group.

#define _100NS_IN_1MS 10000

HANDLE hContext = NULL;
LARGE_INTEGER period, timeout;
GUID guid = { 0 };
BOOL bRes;

period.QuadPart =  Int32x32To64(_100NS_IN_1MS, 1000);
timeout.QuadPart = Int32x32To64(_100NS_IN_1MS, 1000);

// Create the thread ordering group.
bRes = AvRtCreateThreadOrderingGroup(
        &hContext,
        &period,
        &guid,
        &timeout);
if(bRes == FALSE )
{
    printf("Error creating group (%d)\n", GetLastError());
    return;
}

Executing Code as a Member of a Thread Ordering Group

The following example demonstrates executing code as part of a thread ordering group. This task can be performed by the parent thread and client threads. The variable hContext is set by calling AvRtCreateThreadOrderingGroup, which is shown in Creating a Thread Ordering Group. For client threads the context is obtained by calling the AvRtJoinThreadOrderingGroup function, which is shown in Joining a Thread Ordering Group.

while(AvRtWaitOnThreadOrderingGroup(hContext))
{
    // Do processing for each time interval here.
}

Deleting a Thread Ordering Group

The following example demonstrates deleting a thread ordering group. The variable hContext is set by calling AvRtCreateThreadOrderingGroup, which is shown in Creating a Thread Ordering Group.

AvRtDeleteThreadOrderingGroup(hContext);

Client Thread Tasks

The examples in this section demonstrate performing the following client thread tasks:

Joining a thread ordering group
Leaving a thread ordering group

For an example that illustrates executing code as part of a group, see Executing Code as a Member of a Thread Ordering Group. This functionality is the same in parent and client threads.

Joining a Thread Ordering Group

The following code example demonstrates using the AvRtJoinThreadOrderingGroup function to join a thread ordering group. In this example, the GUID that is the unique identifier for a thread ordering group is passed as a parameter to the function executed by the client thread.

DWORD WINAPI AClientThread(LPVOID lpParam)
{
    GUID* pData;
    BOOL groupAlive;
    HANDLE groupContext;
    BOOL scheduleBeforeParent; 

    // Cast the parameter to the correct data type.
    pData = (GUID*)lpParam;

    // Join as a successor, not a predecessor.
    scheduleBeforeParent = FALSE;

    // Join the group.
    groupAlive = AvRtJoinThreadOrderingGroup(
        &groupContext,
        pData,
        scheduleBeforeParent);

    if (groupAlive == FALSE)
    {
        return 2;
    }

Leaving a Thread Ordering Group

The following example demonstrates leaving a thread ordering group. The variable groupContext is set by calling AvRtJoinThreadOrderingGroup, which is shown in Joining a Thread Ordering Group.

AvRtLeaveThreadOrderingGroup(groupContext);