Writing and Installing an Event Handler

To handle the events generated by a dispatch source, you must define an event handler to process those events. An event handler is a function or block object that you install on your dispatch source using the dispatch_source_set_event_handler or dispatch_source_set_event_handler_f function. When an event arrives, the dispatch source submits your event handler to the designated dispatch queue for processing.

The body of your event handler is responsible for processing any events that arrive. If your event handler is already queued and waiting to process an event when a new event arrives, the dispatch source coalesces the two events. An event handler generally sees information only for the most recent event, but depending on the type of the dispatch source it may also be able to get information about other events that occurred and were coalesced. If one or more new events arrive after the event handler has begun executing, the dispatch source holds onto those events until the current event handler has finished executing. At that point, it submits the event handler to the queue again with the new events.

Function-based event handlers take a single context pointer, containing the dispatch source object, and return no value. Block-based event handlers take no parameters and have no return value.

// Block-based event handler

void (^dispatch_block_t)(void)

// Function-based event handler

void (*dispatch_function_t)(void *)

Inside your event handler, you can get information about the given event from the dispatch source itself. Although function-based event handlers are passed a pointer to the dispatch source as a parameter, block-based event handlers must capture that pointer themselves. You can do this for your blocks by referencing the variable containing the dispatch source normally. For example, the following code snippet captures the source variable, which is declared outside the scope of the block.

dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_READ,

                                 myDescriptor, 0, myQueue);

dispatch_source_set_event_handler(source, ^{

   // Get some data from the source variable, which is captured

   // from the parent context.

   size_t estimated = dispatch_source_get_data(source);

   // Continue reading the descriptor...

});

dispatch_resume(source);

Capturing variables inside of a block is commonly done to allow for greater flexibility and dynamism. Of course, captured variables are read-only within the block by default. Although the blocks feature provides support for modifying captured variables under specific circumstances, you should not attempt to do so in the event handlers associated with a dispatch source. Dispatch sources always execute their event handlers asynchronously, so the defining scope of any variables you captured is likely gone by the time your event handler executes. For more information about how to capture and use variables inside of blocks, see Blocks Programming Topics.

Table 4-1 lists the functions you can call from your event handler code to obtain information about an event.

For some examples of how to write and install event handlers for specific types of dispatch sources, see Dispatch Source Examples.

Installing a Cancellation Handler

Cancellation handlers are used to clean up a dispatch source before it is released. For most types of dispatch sources, cancellation handlers are optional and only necessary if you have some custom behaviors tied to the dispatch source that also need to be updated. For dispatch sources that use a descriptor or Mach port, however, you must provide a cancellation handler to close the descriptor or release the Mach port. Failure to do so can lead to subtle bugs in your code resulting from those structures being reused unintentionally by your code or other parts of the system.

You can install a cancellation handler at any time but usually you would do so when creating the dispatch source. You install a cancellation handler using the dispatch_source_set_cancel_handler or dispatch_source_set_cancel_handler_f function, depending on whether you want to use a block object or a function in your implementation. The following example shows a simple cancellation handler that closes a descriptor that was opened for a dispatch source. The fd variable is a captured variable containing the descriptor.

dispatch_source_set_cancel_handler(mySource, ^{

   close(fd); // Close a file descriptor opened earlier.

});

To see a complete code example for a dispatch source that uses a cancellation handler, see Reading Data from a Descriptor.

Changing the Target Queue

Although you specify the queue on which to run your event and cancellation handlers when you create a dispatch source, you can change that queue at any time using the dispatch_set_target_queue function. You might do this to change the priority at which the dispatch source’s events are processed.

Changing a dispatch source’s queue is an asynchronous operation and the dispatch source does its best to make the change as quickly as possible. If an event handler is already queued and waiting to be processed, it executes on the previous queue. However, other events arriving around the time you make the change could be processed on either queue.

Associating Custom Data with a Dispatch Source

Like many other data types in Grand Central Dispatch, you can use the dispatch_set_context function to associate custom data with a dispatch source. You can use the context pointer to store any data your event handler needs to process events. If you do store any custom data in the context pointer, you should also install a cancellation handler (as described in Installing a Cancellation Handler) to release that data when the dispatch source is no longer needed.

If you implement your event handler using blocks, you can also capture local variables and use them within your block-based code. Although this might alleviate the need to store data in the context pointer of the dispatch source, you should always use this feature judiciously. Because dispatch sources may be long-lived in your application, you should be careful when capturing variables containing pointers. If the data pointed to by a pointer could be deallocated at any time, you should either copy the data or retain it to prevent that from happening. In either case, you would then need to provide a cancellation handler to release the data later.

Memory Management for Dispatch Sources

Like other dispatch objects, dispatch sources are reference counted data types. A dispatch source has an initial reference count of 1 and can be retained and released using the dispatch_retain and dispatch_release functions. When the reference count of a queue reaches zero, the system automatically deallocates the dispatch source data structures.

Because of the way they are used, the ownership of dispatch sources can be managed either internally or externally to the dispatch source itself. With external ownership, another object or piece of code takes ownership of the dispatch source and is responsible for releasing it when it is no longer needed. With internal ownership, the dispatch source owns itself and is responsible for releasing itself at the appropriate time. Although external ownership is very common, you might use internal ownership in cases where you want to create an autonomous dispatch source and let it manage some behavior of your code without any further interactions. For example, if a dispatch source is designed to respond to a single global event, you might have it handle that event and then exit immediately.

Creating a Timer

Timer dispatch sources generate events at regular, time-based intervals. You can use timers to initiate specific tasks that need to be performed regularly. For example, games and other graphics-intensive applications might use timers to initiate screen or animation updates. You could also set up a timer and use the resulting events to check for new information on a frequently updated server.

All timer dispatch sources are interval timers—that is, once created, they deliver regular events at the interval you specify. When you create a timer dispatch source, one of the values you must specify is a leeway value to give the system some idea of the desired accuracy for timer events. Leeway values give the system some flexibility in how it manages power and wakes up cores. For example, the system might use the leeway value to advance or delay the fire time and align it better with other system events. You should therefore specify a leeway value whenever possible for your own timers.

When a computer goes to sleep, all timer dispatch sources are suspended. When the computer wakes up, those timer dispatch sources are automatically woken up as well. Depending on the configuration of the timer, pauses of this nature may affect when your timer fires next. If you set up your timer dispatch source using the dispatch_time function or the DISPATCH_TIME_NOW constant, the timer dispatch source uses the default system clock to determine when to fire. However, the default clock does not advance while the computer is asleep. By contrast, when you set up your timer dispatch source using the dispatch_walltime function, the timer dispatch source tracks its firing time to the wall clock time. This latter option is typically appropriate for timers whose firing interval is relatively large because it prevents there from being too much drift between event times.

Listing 4-1 shows an example of a timer that fires once every 30 seconds and has a leeway value of 1 second. Because the timer interval is relatively large, the dispatch source is created using the dispatch_walltime function. The first firing of the timer occurs immediately and subsequent events arrive every 30 seconds. The MyPeriodicTask and MyStoreTimer symbols represent custom functions that you would write to implement the timer behavior and to store the timer somewhere in your application’s data structures.

Listing 4-1  Creating a timer dispatch source

dispatch_source_t CreateDispatchTimer(uint64_t interval,

              uint64_t leeway,

              dispatch_queue_t queue,

              dispatch_block_t block)

{

   dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER,

                                                     0, 0, queue);

   if (timer)

   {

      dispatch_source_set_timer(timer, dispatch_walltime(NULL, 0), interval, leeway);

      dispatch_source_set_event_handler(timer, block);

      dispatch_resume(timer);

   }

   return timer;

}

void MyCreateTimer()

{

   dispatch_source_t aTimer = CreateDispatchTimer(30ull * NSEC_PER_SEC,

                               1ull * NSEC_PER_SEC,

                               dispatch_get_main_queue(),

                               ^{ MyPeriodicTask(); });

   // Store it somewhere for later use.

    if (aTimer)

    {

        MyStoreTimer(aTimer);

    }

}

Although creating a timer dispatch source is the main way to receive time-based events, there are other options available as well. If you want to perform a block once after a specified time interval, you can use the dispatch_after or dispatch_after_f function. This function behaves much like the dispatch_async function except that it allows you to specify a time value at which to submit the block to a queue. The time value can be specified as a relative or absolute time value depending on your needs.

Reading Data from a Descriptor

To read data from a file or socket, you must open the file or socket and create a dispatch source of type DISPATCH_SOURCE_TYPE_READ. The event handler you specify should be capable of reading and processing the contents of the file descriptor. In the case of a file, this amounts to reading the file data (or a subset of that data) and creating the appropriate data structures for your application. For a network socket, this involves processing newly received network data.

Whenever reading data, you should always configure your descriptor to use non-blocking operations. Although you can use the dispatch_source_get_data function to see how much data is available for reading, the number returned by that function could change between the time you make the call and the time you actually read the data. If the underlying file is truncated or a network error occurs, reading from a descriptor that blocks the current thread could stall your event handler in mid execution and prevent the dispatch queue from dispatching other tasks. For a serial queue, this could deadlock your queue, and even for a concurrent queue this reduces the number of new tasks that can be started.

Listing 4-2 shows an example that configures a dispatch source to read data from a file. In this example, the event handler reads the entire contents of the specified file into a buffer and calls a custom function (that you would define in your own code) to process the data. (The caller of this function would use the returned dispatch source to cancel it once the read operation was completed.) To ensure that the dispatch queue does not block unnecessarily when there is no data to read, this example uses the fcntl function to configure the file descriptor to perform nonblocking operations. The cancellation handler installed on the dispatch source ensures that the file descriptor is closed after the data is read.

Listing 4-2  Reading data from a file

dispatch_source_t ProcessContentsOfFile(const char* filename)

{

   // Prepare the file for reading.

   int fd = open(filename, O_RDONLY);

   if (fd == -1)

      return NULL;

   fcntl(fd, F_SETFL, O_NONBLOCK);  // Avoid blocking the read operation

   dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

   dispatch_source_t readSource = dispatch_source_create(DISPATCH_SOURCE_TYPE_READ,

                                   fd, 0, queue);

   if (!readSource)

   {

      close(fd);

      return NULL;

   }

   // Install the event handler

   dispatch_source_set_event_handler(readSource, ^{

      size_t estimated = dispatch_source_get_data(readSource) + 1;

      // Read the data into a text buffer.

      char* buffer = (char*)malloc(estimated);

      if (buffer)

      {

         ssize_t actual = read(fd, buffer, (estimated));

         Boolean done = MyProcessFileData(buffer, actual);  // Process the data.

         // Release the buffer when done.

         free(buffer);

         // If there is no more data, cancel the source.

         if (done)

            dispatch_source_cancel(readSource);

      }

    });

   // Install the cancellation handler

   dispatch_source_set_cancel_handler(readSource, ^{close(fd);});

   // Start reading the file.

   dispatch_resume(readSource);

   return readSource;

}

In the preceding example, the custom MyProcessFileData function determines when enough file data has been read and the dispatch source can be canceled. By default, a dispatch source configured for reading from a descriptor schedules its event handler repeatedly while there is still data to read. If the socket connection closes or you reach the end of a file, the dispatch source automatically stops scheduling the event handler. If you know you do not need a dispatch source though, you can cancel it directly yourself.

Writing Data to a Descriptor

The process for writing data to a file or socket is very similar to the process for reading data. After configuring a descriptor for write operations, you create a dispatch source of type DISPATCH_SOURCE_TYPE_WRITE. Once that dispatch source is created, the system calls your event handler to give it a chance to start writing data to the file or socket. When you are finished writing data, use the dispatch_source_cancel function to cancel the dispatch source.

Whenever writing data, you should always configure your file descriptor to use non-blocking operations. Although you can use the dispatch_source_get_data function to see how much space is available for writing, the value returned by that function is advisory only and could change between the time you make the call and the time you actually write the data. If an error occurs, writing data to a blocking file descriptor could stall your event handler in mid execution and prevent the dispatch queue from dispatching other tasks. For a serial queue, this could deadlock your queue, and even for a concurrent queue this reduces the number of new tasks that can be started.

Listing 4-3 shows the basic approach for writing data to a file using a dispatch source. After creating the new file, this function passes the resulting file descriptor to its event handler. The data being put into the file is provided by the MyGetData function, which you would replace with whatever code you needed to generate the data for the file. After writing the data to the file, the event handler cancels the dispatch source to prevent it from being called again. The owner of the dispatch source would then be responsible for releasing it.

Listing 4-3  Writing data to a file

dispatch_source_t WriteDataToFile(const char* filename)

{

    int fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,

                      (S_IRUSR | S_IWUSR | S_ISUID | S_ISGID));

    if (fd == -1)

        return NULL;

    fcntl(fd, F_SETFL); // Block during the write.

    dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

    dispatch_source_t writeSource = dispatch_source_create(DISPATCH_SOURCE_TYPE_WRITE,

                            fd, 0, queue);

    if (!writeSource)

    {

        close(fd);

        return NULL;

    }

    dispatch_source_set_event_handler(writeSource, ^{

        size_t bufferSize = MyGetDataSize();

        void* buffer = malloc(bufferSize);

        size_t actual = MyGetData(buffer, bufferSize);

        write(fd, buffer, actual);

        free(buffer);

        // Cancel and release the dispatch source when done.

        dispatch_source_cancel(writeSource);

    });

    dispatch_source_set_cancel_handler(writeSource, ^{close(fd);});

    dispatch_resume(writeSource);

    return (writeSource);

}

Monitoring a File-System Object

If you want to monitor a file system object for changes, you can set up a dispatch source of type DISPATCH_SOURCE_TYPE_VNODE. You can use this type of dispatch source to receive notifications when a file is deleted, written to, or renamed. You can also use it to be alerted when specific types of meta information for a file (such as its size and link count) change.

Listing 4-4 shows an example that monitors a file for name changes and performs some custom behavior when it does. (You would provide the actual behavior in place of the MyUpdateFileName function called in the example.) Because a descriptor is opened specifically for the dispatch source, the dispatch source includes a cancellation handler that closes the descriptor. Because the file descriptor created by the example is associated with the underlying file-system object, this same dispatch source can be used to detect any number of filename changes.

Listing 4-4  Watching for filename changes

dispatch_source_t MonitorNameChangesToFile(const char* filename)

{

   int fd = open(filename, O_EVTONLY);

   if (fd == -1)

      return NULL;

   dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

   dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_VNODE,

                fd, DISPATCH_VNODE_RENAME, queue);

   if (source)

   {

      // Copy the filename for later use.

      int length = strlen(filename);

      char* newString = (char*)malloc(length + 1);

      newString = strcpy(newString, filename);

      dispatch_set_context(source, newString);

      // Install the event handler to process the name change

      dispatch_source_set_event_handler(source, ^{

            const char*  oldFilename = (char*)dispatch_get_context(source);

            MyUpdateFileName(oldFilename, fd);

      });

      // Install a cancellation handler to free the descriptor

      // and the stored string.

      dispatch_source_set_cancel_handler(source, ^{

          char* fileStr = (char*)dispatch_get_context(source);

          free(fileStr);

          close(fd);

      });

      // Start processing events.

      dispatch_resume(source);

   }

   else

      close(fd);

   return source;

}

Monitoring Signals

UNIX signals allow the manipulation of an application from outside of its domain. An application can receive many different types of signals ranging from unrecoverable errors (such as illegal instructions) to notifications about important information (such as when a child process exits). Traditionally, applications use the sigaction function to install a signal handler function, which processes signals synchronously as soon as they arrive. If you just want to be notified of a signal’s arrival and do not actually want to handle the signal, you can use a signal dispatch source to process the signals asynchronously.

Signal dispatch sources are not a replacement for the synchronous signal handlers you install using the sigaction function. Synchronous signal handlers can actually catch a signal and prevent it from terminating your application. Signal dispatch sources allow you to monitor only the arrival of the signal. In addition, you cannot use signal dispatch sources to retrieve all types of signals. Specifically, you cannot use them to monitor the SIGILL, SIGBUS, and SIGSEGV signals.

Because signal dispatch sources are executed asynchronously on a dispatch queue, they do not suffer from some of the same limitations as synchronous signal handlers. For example, there are no restrictions on the functions you can call from your signal dispatch source’s event handler. The tradeoff for this increased flexibility is the fact that there may be some increased latency between the time a signal arrives and the time your dispatch source’s event handler is called.

Listing 4-5 shows how you configure a signal dispatch source to handle the SIGHUP signal. The event handler for the dispatch source calls the MyProcessSIGHUP function, which you would replace in your application with code to process the signal.

Listing 4-5  Installing a block to monitor signals

void InstallSignalHandler()

{

   // Make sure the signal does not terminate the application.

   signal(SIGHUP, SIG_IGN);

   dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

   dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_SIGNAL, SIGHUP, 0, queue);

   if (source)

   {

      dispatch_source_set_event_handler(source, ^{

         MyProcessSIGHUP();

      });

      // Start processing signals

      dispatch_resume(source);

   }

}

If you are developing code for a custom framework, an advantage of using signal dispatch sources is that your code can monitor signals independent of any applications linked to it. Signal dispatch sources do not interfere with other dispatch sources or any synchronous signal handlers the application might have installed.

For more information about implementing synchronous signal handlers, and for a list of signal names, see signal man page.

Monitoring a Process

A process dispatch source lets you monitor the behavior of a specific process and respond appropriately. A parent process might use this type of dispatch source to monitor any child processes it creates. For example, the parent process could use it to watch for the death of a child process. Similarly, a child process could use it to monitor its parent process and exit if the parent process exits.

Listing 4-6 shows the steps for installing a dispatch source to monitor for the termination of a parent process. When the parent process dies, the dispatch source sets some internal state information to let the child process know it should exit. (Your own application would need to implement the MySetAppExitFlag function to set an appropriate flag for termination.) Because the dispatch source runs autonomously, and therefore owns itself, it also cancels and releases itself in anticipation of the program shutting down.

Listing 4-6  Monitoring the death of a parent process

void MonitorParentProcess()

{

   pid_t parentPID = getppid();

   dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

   dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_PROC,

                                                      parentPID, DISPATCH_PROC_EXIT, queue);

   if (source)

   {

      dispatch_source_set_event_handler(source, ^{

         MySetAppExitFlag();

         dispatch_source_cancel(source);

         dispatch_release(source);

      });

      dispatch_resume(source);

   }

}