====== 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.

^ Branch ^ Date ^ Minimum SVN revision ^
| 7-STABLE | unsupported | unsupported |
| 8-STABLE | 2009-11-01 | r198732 |
| 9-CURRENT | 2009-09-18 | r197293 |

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 =====

  - Install %%FreeBSD%% 8.1 (or later).
  - 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:

<code>
#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);
}
</code>

Compile this with:

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

===== The same program, without C Blocks =====

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

<code>
#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);
}
</code>

Compile this with:

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

===== Experimental Patches =====

  * [[https://reviews.freebsd.org/D3189|D3189]] based on Stacy Son's [[http://people.freebsd.org/~sson/thrworkq/|PThread Workqueues for FreeBSD 9.0]]

===== Useful references =====

[[http://youtu.be/nhbA9jZyYO4|Demo with GCD in action]]

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

[[http://www.freebsd.org/news/status/report-2009-04-2009-09.html#Grand-Central-Dispatch---FreeBSD-port|April-September 2009 FreeBSD status report - Grand Central Dispatch port]] - status on the %%FreeBSD%% port of GCD

[[http://libdispatch.macosforge.org/|Mac OS X Forge - open source libdispatch home]] - libdispatch subversion repository and mailing lists

[[http://web.archive.org/web/20090920043909/http://images.apple.com/macosx/technology/docs/GrandCentral_TB_brief_20090903.pdf|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.

{{GrandCentralDispatch/20090918-devsummit-gcd-public.pdf?linkonly|20090918-devsummit-gcd-public.pdf}} - 2008 DevSummit Presentation