Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dispatch_source_creat... BSD Library Functions Manual dispatch_source_creat...

NAME
     dispatch_source_create -- dispatch	event sources

SYNOPSIS
     #include <dispatch/dispatch.h>

     dispatch_source_t
     dispatch_source_create(dispatch_source_type_t type, uintptr_t handle,
	 unsigned long mask, dispatch_queue_t queue);

     void
     dispatch_source_set_event_handler(dispatch_source_t source,
	 void (^block)(void));

     void
     dispatch_source_set_event_handler_f(dispatch_source_t source,
	 void (*function)(void *));

     void
     dispatch_source_set_cancel_handler(dispatch_source_t source,
	 void (^block)(void));

     void
     dispatch_source_set_cancel_handler_f(dispatch_source_t source,
	 void (*function)(void *));

     void
     dispatch_source_cancel(dispatch_source_t source);

     void
     dispatch_source_testcancel(dispatch_source_t source);

     uintptr_t
     dispatch_source_get_handle(dispatch_source_t source);

     unsigned long
     dispatch_source_get_mask(dispatch_source_t	source);

     unsigned long
     dispatch_source_get_data(dispatch_source_t	source);

     void
     dispatch_source_merge_data(dispatch_source_t source, unsigned long	data);

     void
     dispatch_source_set_timer(dispatch_source_t source,
	 dispatch_time_t start,	uint64_t interval, uint64_t leeway);

DESCRIPTION
     Dispatch event sources may	be used	to monitor a variety of	system objects
     and events	including file descriptors, mach ports,	processes, virtual
     filesystem	nodes, signal delivery and timers.

     When a state change occurs, the dispatch source will submit its event
     handler block to its target queue.

     The dispatch_source_create() function creates a new dispatch source ob-
     ject that may be retained and released with calls to dispatch_retain()
     and dispatch_release() respectively. Newly	created	sources	are created in
     a suspended state.	After the source has been configured by	setting	an
     event handler, cancellation handler, context, etc., the source must be
     activated by a call to dispatch_resume() before any events	will be	deliv-
     ered.

     Dispatch sources may be one of the	following types:
	   +o   DISPATCH_SOURCE_TYPE_DATA_ADD
	   +o   DISPATCH_SOURCE_TYPE_DATA_OR
	   +o   DISPATCH_SOURCE_TYPE_MACH_SEND
	   +o   DISPATCH_SOURCE_TYPE_MACH_RECV
	   +o   DISPATCH_SOURCE_TYPE_PROC
	   +o   DISPATCH_SOURCE_TYPE_READ
	   +o   DISPATCH_SOURCE_TYPE_SIGNAL
	   +o   DISPATCH_SOURCE_TYPE_TIMER
	   +o   DISPATCH_SOURCE_TYPE_VNODE
	   +o   DISPATCH_SOURCE_TYPE_WRITE

     The handle	and mask arguments to dispatch_source_create() and the return
     values of the dispatch_source_get_handle(), dispatch_source_get_mask(),
     and dispatch_source_get_data() functions should be	interpreted according
     to	the type of the	dispatch source.

     The dispatch_source_get_handle() function returns the underlying handle
     to	the dispatch source (i.e. file descriptor, mach	port, process identi-
     fer, etc.). The result of this function may be cast directly to the un-
     derlying type.

     The dispatch_source_get_mask() function returns the set of	flags that
     were specified at source creation time via	the mask argument.

     The dispatch_source_get_data() function returns the currently pending
     data for the dispatch source.  This function should only be called	from
     within the	source's event handler.	 The result of calling this function
     from any other context is undefined.

     The dispatch_source_merge_data() function is intended for use with	the
     DISPATCH_SOURCE_TYPE_DATA_ADD and DISPATCH_SOURCE_TYPE_DATA_OR source
     types. The	result of using	this function with any other source type is
     undefined.	Calling	this function will atomically add or logical OR	the
     data into the source's data, and trigger the delivery of the source's
     event handler.

SOURCE EVENT HANDLERS
     In	order to receive events	from the dispatch source, an event handler
     should be specified via dispatch_source_set_event_handler().  The event
     handler block is submitted	to the source's	target queue when the state of
     the underlying system handle changes, or when an event occurs.

     Dispatch sources may be suspended or resumed independently	of their tar-
     get queues	using dispatch_suspend() and dispatch_resume() on the dispatch
     source directly. The data describing events which occur while a source is
     suspended are coalesced and delivered once	the source is resumed.

     The handler block need not	be reentrant safe, as it is not	resubmitted to
     the target	queue until any	prior invocation for that dispatch source has
     completed.	 When the handler is set, the dispatch source will perform a
     Block_copy() on the handler block.

CANCELLATION
     The dispatch_source_cancel() function asynchronously cancels the dispatch
     source, preventing	any further invocation of its event handler block.
     Cancellation does not interrupt a currently executing handler block (non-
     preemptive).

     The dispatch_source_testcancel() function may be used to determine
     whether the specified source has been canceled. A non-zero	value will be
     returned if the source is canceled.

     When a dispatch source is canceled	its optional cancellation handler will
     be	submitted to its target	queue. The cancellation	handler	may be speci-
     fied via dispatch_source_set_cancel_handler().  This cancellation handler
     is	invoked	only once, and only as a direct	consequence of calling
     dispatch_source_cancel().

     Important:	a cancellation handler is required for file descriptor and
     mach port based sources in	order to safely	close the descriptor or	de-
     stroy the port. Closing the descriptor or port before the cancellation
     handler has run may result	in a race condition: if	a new descriptor is
     allocated with the	same value as the recently closed descriptor while the
     source's event handler is still running, the event	handler	may read/write
     data to the wrong descriptor.

DISPATCH SOURCE	TYPES
     The following section contains a summary of supported dispatch event
     types and the interpretation of their parameters and returned data.

     DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR

     Sources of	this type allow	applications to	manually trigger the source's
     event handler via a call to dispatch_source_merge_data().	The data will
     be	merged with the	source's pending data via an atomic add	or logic OR
     (based on the source's type), and the event handler block will be submit-
     ted to the	source's target	queue. The data	is application defined.	These
     sources have no handle or mask and	zero should be used.

     DISPATCH_SOURCE_TYPE_MACH_SEND

     Sources of	this type monitor a mach port with a send right	for state
     changes.  The handle is the mach port (mach_port_t) to monitor and	the
     mask may be:
	   o DISPATCH_MACH_SEND_DEAD
				   The port's corresponding receive right has
				   been	destroyed

     The data returned by dispatch_source_get_data() indicates which of	the
     events in the mask	were observed.

     DISPATCH_SOURCE_TYPE_MACH_RECV

     Sources of	this type monitor a mach port with a receive right for state
     changes.  The handle is the mach port (mach_port_t) to monitor and	the
     mask is unused and	should be zero.	 The event handler block will be sub-
     mitted to the target queue	when a message on the mach port	is waiting to
     be	received.

     DISPATCH_SOURCE_TYPE_PROC

     Sources of	this type monitor processes for	state changes.	The handle is
     the process identifier (pid_t) of the process to monitor and the mask may
     be	one or more of the following:
	   o DISPATCH_PROC_EXIT	   The process has exited and is available to
				   wait(2).
	   o DISPATCH_PROC_FORK	   The process has created one or more child
				   processes.
	   o DISPATCH_PROC_EXEC	   The process has become another executable
				   image via a call to execve(2) or
				   posix_spawn(2).
	   o DISPATCH_PROC_REAP	   The process status has been collected by
				   its parent process via wait(2).
	   o DISPATCH_PROC_SIGNAL  A signal was	delivered to the process.

     The data returned by dispatch_source_get_data() indicates which of	the
     events in the mask	were observed.

     DISPATCH_SOURCE_TYPE_READ

     Sources of	this type monitor file descriptors for pending data.  The
     handle is the file	descriptor (int) to monitor and	the mask is unused and
     should be zero.

     The data returned by dispatch_source_get_data() is	an estimated number of
     bytes available to	be read	from the descriptor. This estimate should be
     treated as	a suggested minimum read buffer	size. There are	no guarantees
     that a complete read of this size will be performed.

     Users of this source type are strongly encouraged to perform non-blocking
     I/O and handle any	truncated reads	or error conditions that may occur.
     See fcntl(2) for additional information about setting the O_NONBLOCK flag
     on	a file descriptor.

     DISPATCH_SOURCE_TYPE_SIGNAL

     Sources of	this type monitor signals delivered to the current process.
     The handle	is the signal number to	monitor	(int) and the mask is unused
     and should	be zero.

     The data returned by dispatch_source_get_data() is	the number of signals
     received since the	last invocation	of the event handler block.

     Unlike signal handlers specified via sigaction(), the execution of	the
     event handler block does not interrupt the	current	thread of execution;
     therefore the handler block is not	limited	to the use of signal safe in-
     terfaces defined in sigaction(2).	Furthermore, multiple observers	of a
     given signal are supported; thus allowing applications and	libraries to
     cooperate safely. However,	a dispatch source does not install a signal
     handler or	otherwise alter	the behavior of	signal delivery.  Therefore,
     applications must ignore or at least catch	any signal that	terminates a
     process by	default. For example, near the top of main():

	  signal(SIGTERM, SIG_IGN);

     DISPATCH_SOURCE_TYPE_TIMER

     Sources of	this type periodically submit the event	handler	block to the
     target queue on an	interval specified by dispatch_source_set_timer().
     The handle	and mask arguments are unused and should be zero.

     A best effort attempt is made to submit the event handler block to	the
     target queue at the specified time; however, actual invocation may	occur
     at	a later	time.

     The data returned by dispatch_source_get_data() is	the number of times
     the timer has fired since the last	invocation of the event	handler	block.

     The function dispatch_source_set_timer() takes as an argument the start
     time of the timer (initial	fire time) represented as a dispatch_time_t.
     The timer dispatch	source will use	the same clock as the function used to
     create this value.	(See dispatch_time(3) for more information.) The
     interval, in nanoseconds, specifies the period at which the timer should
     repeat. All timers	will repeat indefinitely until
     dispatch_source_cancel() is called. The leeway, in	nanoseconds, is	a hint
     to	the system that	it may defer the timer in order	to align with other
     system activity for improved system performance or	reduced	power consump-
     tion. (For	example, an application	might perform a	periodic task every 5
     minutes with a leeway of up to 30 seconds.) Note that some	latency	is to
     be	expected for all timers	even when a value of zero is used.

     Note: Under the C language, untyped numbers default to the	int type. This
     can lead to truncation bugs when arithmetic operations with other numbers
     are expected to generate a	uint64_t sized result. When in doubt, use ull
     as	a suffix. For example:

	   3ull	* NSEC_PER_SEC

     DISPATCH_SOURCE_TYPE_VNODE

     Sources of	this type monitor the virtual filesystem nodes for state
     changes.  The handle is a file descriptor (int) referencing the node to
     monitor, and the mask may be one or more of the following:
	   o DISPATCH_VNODE_DELETE  The	referenced node	was removed from the
				    filesystem namespace via unlink(2).
	   o DISPATCH_VNODE_WRITE   A write to the referenced file occurred
	   o DISPATCH_VNODE_EXTEND  The	referenced file	was extended
	   o DISPATCH_VNODE_ATTRIB  The	metadata attributes of the referenced
				    node have changed
	   o DISPATCH_VNODE_LINK    The	link count on the referenced node has
				    changed
	   o DISPATCH_VNODE_RENAME  The	referenced node	was renamed
	   o DISPATCH_VNODE_REVOKE  Access to the referenced node was revoked
				    via	revoke(2) or the underlying fileystem
				    was	unmounted.

     The data returned by dispatch_source_get_data() indicates which of	the
     events in the mask	were observed.

     DISPATCH_SOURCE_TYPE_WRITE

     Sources of	this type monitor file descriptors for available write buffer
     space.  The handle	is the file descriptor (int) to	monitor	and the	mask
     is	unused and should be zero.

     Users of this source type are strongly encouraged to perform non-blocking
     I/O and handle any	truncated reads	or error conditions that may occur.
     See fcntl(2) for additional information about setting the O_NONBLOCK flag
     on	a file descriptor.

SEE ALSO
     dispatch(3), dispatch_object(3), dispatch_queue_create(3)

Darwin				  May 1, 2009				Darwin

NAME | SYNOPSIS | DESCRIPTION | SOURCE EVENT HANDLERS | CANCELLATION | DISPATCH SOURCE TYPES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dispatch_source_create&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help