• GrandCentralDispatch

Grand Central Dispatch (GCD) on FreeBSD

This is a status and quick-start page on using Apple's Grand Central Dispatch (GCD) technology on the FreeBSD operating system. GCD support on FreeBSD was added by RobertWatson and StaceySon; the port is maintained by StanislavSedov.

Status

GCD support is considered production-worthy on FreeBSD 8.1 and later, and requires recent versions of the llvm-devel and compiler-rt ports. The kernel extensions required to support libdispatch first appeared in FreeBSD 8.1.

Experimental patches exist to add pthread workqueue support to the FreeBSD 9.x kernel, but are not present in shipped kernels (including 9-CURRENT).

Quick-start

1. Install FreeBSD 8.1 (or later).

2. Install the devel/libdispatch port, which will install llvm-devel and compiler-rt as dependencies.

libdispatch works fine with gcc as shipped with FreeBSD for the function-centric interface dispatch APIs, but to use C Blocks you will need to build with clang -fblocks. Also, llvm-gcc4 (derived from Apple's gcc) and will work but is unsupported upstream.

As of version 10.0, FreeBSD ships with clang and compiler_rt in the base system so GCD is available out of the box. On Tier-2 platforms, where clang is not yet shipped by default, support for blocks has been added to GCC in base.

To build applications with libdispatch, add -I/usr/local/include to compiler command lines, and -L/usr/local/lib -ldispatch to linker command lines.

A simple GCD program

This program schedules deferred execution of a C block that prints a message and exits:

#include <dispatch/dispatch.h>

#include <err.h>
#include <stdio.h>
#include <stdlib.h>

int
main(int argc, char *argv[])
{
        dispatch_queue_t q;
        dispatch_time_t t;

        q = dispatch_get_main_queue();
        t = dispatch_time(DISPATCH_TIME_NOW, 5LL * NSEC_PER_SEC);

        // Print a message and exit after 5 seconds.
        dispatch_after(t, q, ^{
                printf("block_dispatch\n");
                exit(0);
            });

        dispatch_main();
        return (0);
}

Compile this with:

clang -Wall -Werror -fblocks -L/usr/local/lib -I/usr/local/include -o test test.c -ldispatch

The same program, without C Blocks

Here's a similar program, performing the same work but using deferred functions rather than C Blocks:

#include <dispatch/dispatch.h>

#include <err.h>
#include <stdio.h>
#include <stdlib.h>

void
deferred_code(__unused void *arg)
{

        printf("block_dispatch\n");
        exit(0);
}

int
main(int argc, char *argv[])
{
        dispatch_queue_t q;
        dispatch_time_t t;

        q = dispatch_get_main_queue();
        t = dispatch_time(DISPATCH_TIME_NOW, 5LL * NSEC_PER_SEC);

        dispatch_after_f(t, q, NULL, deferred_code);

        dispatch_main();
        return (0);
}

Compile this with:

gcc -Wall -Werror -I/usr/local/include -L/usr/local/lib -o test2 test2.c -ldispatch

Experimental Patches

• D3189 based on Stacy Son's PThread Workqueues for FreeBSD 9.0

Useful references

Demo with GCD in action

libdispatch ships with informative man pages describing not just the API, but also how to structure programs around GCD.

April-September 2009 FreeBSD status report - Grand Central Dispatch port - status on the FreeBSD port of GCD

Mac OS X Forge - open source libdispatch home - libdispatch subversion repository and mailing lists

Grand Central Dispatch: Technology Brief - a white paper from Apple introducing GCD.

Mac OS X Reference Library: Concurrency Programming Guide - a guide to concurrent programming on Mac OS X, much of which also applies to FreeBSD with the GCD port installed.

Mac Dev Center: Grand Central Dispatch Reference - reference material on GCD from Apple.

Mac OS Reference Library: Dispatch_Samples - sample code using GCD from Apple.

20090918-devsummit-gcd-public.pdf - 2008 DevSummit Presentation