[apple/libdispatch.git] / man / dispatch_once.3

.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
.Dd May 1, 2009
.Dt dispatch_once 3
.Os Darwin
.Sh NAME
.Nm dispatch_once
.Nd execute a block only once
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft void
.Fo dispatch_once
.Fa "dispatch_once_t *predicate" "void (^block)(void)"
.Fc
.Ft void
.Fo dispatch_once_f
.Fa "dispatch_once_t *predicate" "void *context" "void (*function)(void *)"
.Fc
.Sh DESCRIPTION
The
.Fn dispatch_once
function provides a simple and efficient mechanism to run an initializer
exactly once, similar to
.Xr pthread_once 3 .
Well designed code hides the use of lazy initialization.
For example:
.Bd -literal
FILE *getlogfile(void)
{
	static dispatch_once_t pred;
	static FILE *logfile;

	dispatch_once(&pred, ^{
		logfile = fopen(MY_LOG_FILE, "a");
	});

	return logfile;
}
.Ed
.Pp
.Sh FUNDAMENTALS
The
.Fn dispatch_once
function is a wrapper around
.Fn dispatch_once_f .
.Sh SEE ALSO
.Xr dispatch 3
Commit	Line	Data
0ab74447 A	1	.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
	2	.Dd May 1, 2009
	3	.Dt dispatch_once 3
	4	.Os Darwin
	5	.Sh NAME
	6	.Nm dispatch_once
	7	.Nd execute a block only once
	8	.Sh SYNOPSIS
	9	.Fd #include <dispatch/dispatch.h>
	10	.Ft void
	11	.Fo dispatch_once
	12	.Fa "dispatch_once_t *predicate" "void (^block)(void)"
	13	.Fc
	14	.Ft void
	15	.Fo dispatch_once_f
	16	.Fa "dispatch_once_t predicate" "void context" "void (function)(void )"
	17	.Fc
	18	.Sh DESCRIPTION
	19	The
	20	.Fn dispatch_once
	21	function provides a simple and efficient mechanism to run an initializer
	22	exactly once, similar to
	23	.Xr pthread_once 3 .
	24	Well designed code hides the use of lazy initialization.
	25	For example:
	26	.Bd -literal
	27	FILE *getlogfile(void)
	28	{
	29	static dispatch_once_t pred;
	30	static FILE *logfile;
	31
	32	dispatch_once(&pred, ^{
	33	logfile = fopen(MY_LOG_FILE, "a");
	34	});
	35
	36	return logfile;
	37	}
	38	.Ed
	39	.Pp
	40	.Sh FUNDAMENTALS
	41	The
	42	.Fn dispatch_once
	43	function is a wrapper around
	44	.Fn dispatch_once_f .
e85f4437 A	45	.Sh SEE ALSO
e85f4437 A	46	.Xr dispatch 3