How to respond to named events and semaphores (XAML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Learn how to run thread pool work items in response to named events and semaphores.

Note  Apps and Windows Runtime components created with Win32 and COM for Windows Store apps can create events and semaphores by calling CreateEventExW and CreateSemaphoreExW.

Note  Apps and Windows Runtime components created with Win32 and COM for Windows Phone Store apps can create events and semaphores by calling CreateEventEx or CreateSemaphoreEx.

Code written for the Windows Runtime environment can consume named events and semaphores with the SignalNotifier class. Work items can be attached to an event with the AttachToEvent method, and they can be attached to a semaphore with the AttachToSemaphore method. This topic shows steps and code examples for both cases.

What you need to know

Technologies

Prerequisites

  • You need to know the name of the event or semaphore the work item responds to.

Instructions

How to attach a work item to an event

  1. Call AttachToEvent to attach a work item to an event. Specify the name of the event using the name parameter and supply a lambda to accomplish the work. Store the SignalNotifier object for use in the next step.

    Optionally provide a timeout value. The thread pool will run the work item when the event occurs or when the timeout occurs, whichever happens first.

    Note  The timedOut parameter passed to the work item handler can be used to recognize if the timeout occurred and modify work item behavior as appropriate.

     

    The following code shows the use of a SignalNotifier with a timeout value of 3 minutes:

    String EventName = "ExampleEvent";
    
    TimeSpan timeout = TimeSpan.FromMinutes(3);
    
    SignalNotifier NamedEventNotifier = SignalNotifier.AttachToEvent(EventName,
            (signalNotifier, timedOut) =>
            {
                // 
                // TODO: Insert code that handles the event.
                // 
    
    
    
                // 
                // Update the UI thread by using the UI core dispatcher.
                // 
                Dispatcher.RunAsync(CoreDispatcherPriority.High,
                    ()=>
                    {
                        // 
                        // UI components can be accessed within this scope.
                        // 
    
    
    
                    });
            }, 
            timeout);
    
    Platform::String ^ EventName = "ExampleEvent";
    
    TimeSpan timeout;
    timeout.Duration = 3 * 60 * 10000000; // 10,000,000 ticks per second
    
    SignalNotifier ^ NamedEventNotifier = SignalNotifier::AttachToEvent(EventName,
        ref new SignalHandler([this] (SignalNotifier^ signalNotifier, bool timedOut)
        {
            // 
            // TODO: Insert code that handles the event.
            // 
    
    
    
            // 
            // Update the UI thread by using the UI core dispatcher.
            // 
            Dispatcher->RunAsync(CoreDispatcherPriority::High,
                ref new DispatchedHandler([=]()
                {
                    // 
                    // UI components can be accessed within this scope.
                    // 
    
    
    
                }));
        }), 
        timeout);
    
  2. Start watching for the event by calling Enable. If you specified a timeout value then the timer starts counting down.

    NamedEventNotifier.Enable();
    
    NamedEventNotifier->Enable();
    
  3. If necessary, call the Terminate method to stop watching for the event. If you specified a timeout value then the timer is cancelled.

    NamedEventNotifier.Terminate();
    
    NamedEventNotifier->Terminate();
    

How to attach a work item to a semaphore

  1. Call AttachToEvent to attach a work item to a semaphore. Specify the name of the semaphore using the name parameter and supply a lambda to accomplish the work. Store the SignalNotifier object for use in the next step.

    Optionally provide a timeout value. The thread pool will run the work item when the semaphore signals or when the timeout occurs, whichever happens first.

    Note  The timedOut parameter passed to the work item handler can be used to recognize if the timeout occurred and modify work item behavior as appropriate.

     

    The following code shows the use of a SignalNotifier with a timeout value:

    String SemaphoreName = "ExampleSemaphore";
    
    TimeSpan timeout = TimeSpan.FromMinutes(3);
    
    SignalNotifier NamedSemaphoreNotifier = SignalNotifier.AttachToSemaphore(SemaphoreName,
            (signalNotifier, timedOut) =>
            {
                // 
                // TODO: Insert code that accomplishes a task.
                // 
    
    
    
                // 
                // Update the UI thread by using the UI core dispatcher.
                // 
                Dispatcher.RunAsync(CoreDispatcherPriority.High,
                    () =>
                    {
                        // 
                        // UI components can be accessed within this scope.
                        // 
    
    
    
                    });
            }, 
            timeout);
    
    Platform::String ^ SemaphoreName = "ExampleSemaphore";
    
    TimeSpan timeout;
    timeout.Duration = 3 * 60 * 10000000; // 10,000,000 ticks per second
    
    SignalNotifier ^ NamedSemaphoreNotifier = SignalNotifier::AttachToSemaphore(SemaphoreName,
        ref new SignalHandler([this] (SignalNotifier^ signalNotifier, bool timedOut)
        {
            // 
            // TODO: Insert code that accomplishes a task.
            // 
    
    
    
            // 
            // Update the UI thread by using the UI core dispatcher.
            // 
            Dispatcher->RunAsync(CoreDispatcherPriority::High,
                ref new DispatchedHandler([=]()
                {
                    // 
                    // UI components can be accessed within this scope.
                    // 
    
    
    
                }));
        }), 
        timeout);
    
  2. Start listening for the semaphore by calling Enable. If you specified a timeout value, the timer starts counting down.

    NamedSemaphoreNotifier.Enable();
    
    NamedSemaphoreNotifier->Enable();
    
  3. If necessary, call the Terminate method to stop listening for the semaphore. If you specified a timeout value, the timer is cancelled.

    NamedSemaphoreNotifier.Terminate();
    
    NamedSemaphoreNotifier->Terminate();
    

Quickstart: Submitting a work item to the thread pool

How to submit a work item using a timer

How to create a periodic work item

How to create and use pre-allocated work items

How to use functions as work item delegates

Best practices for using the thread pool