Struct DispatchSource

Source

#[repr(C)]
pub struct DispatchSource { /* private fields */ }

Expand description

Dispatch source.

Implementations§

Source §

impl DispatchSource

Source

pub unsafe fn new( type: dispatch_source_type_t, handle: usize, mask: usize, queue: Option<&DispatchQueue>, ) -> DispatchRetained<DispatchSource> ⓘ

Creates a new dispatch source to monitor low-level system objects and auto- matically submit a handler block to a dispatch queue in response to events.

Dispatch sources are not reentrant. Any events received while the dispatch source is suspended or while the event handler block is currently executing will be coalesced and delivered after the dispatch source is resumed or the event handler block has returned.

Dispatch sources are created in an inactive state. After creating the source and setting any desired attributes (i.e. the handler, context, etc.), a call must be made to dispatch_activate() in order to begin event delivery.

A source must have been activated before being disposed.

Calling dispatch_set_target_queue() on a source once it has been activated is not allowed (see dispatch_activate() and dispatch_set_target_queue()).

For backward compatibility reasons, dispatch_resume() on an inactive, and not otherwise suspended source has the same effect as calling dispatch_activate(). For new code, using dispatch_activate() is preferred.

Parameter type: Declares the type of the dispatch source. Must be one of the defined dispatch_source_type_t constants.

Parameter handle: The underlying system handle to monitor. The interpretation of this argument is determined by the constant provided in the type parameter.

Parameter mask: A mask of flags specifying which events are desired. The interpretation of this argument is determined by the constant provided in the type parameter.

Parameter queue: The dispatch queue to which the event handler block will be submitted. If queue is DISPATCH_TARGET_QUEUE_DEFAULT, the source will submit the event handler block to the default priority global queue.

Returns: The newly created dispatch source. Or NULL if invalid arguments are passed.

Source

pub unsafe fn set_event_handler_with_block( self: &DispatchSource, handler: dispatch_block_t, )

Source

pub fn set_event_handler_f(self: &DispatchSource, handler: dispatch_function_t)

Sets the event handler function for the given dispatch source.

Parameter source: The dispatch source to modify. The result of passing NULL in this parameter is undefined.

Parameter handler: The event handler function to submit to the source’s target queue. The context parameter passed to the event handler function is the context of the dispatch source current at the time the event handler was set.

Source

pub unsafe fn set_cancel_handler_with_block( self: &DispatchSource, handler: dispatch_block_t, )

Source

pub fn set_cancel_handler_f(self: &DispatchSource, handler: dispatch_function_t)

Sets the cancellation handler function for the given dispatch source.

See dispatch_source_set_cancel_handler() for more details.

Parameter source: The dispatch source to modify. The result of passing NULL in this parameter is undefined.

Parameter handler: The cancellation handler function to submit to the source’s target queue. The context parameter passed to the event handler function is the current context of the dispatch source at the time the handler call is made.

Source

pub fn cancel(self: &DispatchSource)

Asynchronously cancel the dispatch source, preventing any further invocation of its event handler block.

Cancellation prevents any further invocation of the event handler block for the specified dispatch source, but does not interrupt an event handler block that is already in progress.

The cancellation handler is submitted to the source’s target queue once the the source’s event handler has finished, indicating it is now safe to close the source’s handle (i.e. file descriptor or mach port).

See dispatch_source_set_cancel_handler() for more information.

Parameter source: The dispatch source to be canceled. The result of passing NULL in this parameter is undefined.

Source

pub fn testcancel(self: &DispatchSource) -> isize

Tests whether the given dispatch source has been canceled.

Parameter source: The dispatch source to be tested. The result of passing NULL in this parameter is undefined.

Returns: Non-zero if canceled and zero if not canceled.

Source

pub fn handle(self: &DispatchSource) -> usize

Returns the underlying system handle associated with this dispatch source.

Parameter source: The result of passing NULL in this parameter is undefined.

Returns: The return value should be interpreted according to the type of the dispatch source, and may be one of the following handles:

DISPATCH_SOURCE_TYPE_DATA_ADD: n/a DISPATCH_SOURCE_TYPE_DATA_OR: n/a DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a DISPATCH_SOURCE_TYPE_MACH_SEND: mach port (mach_port_t) DISPATCH_SOURCE_TYPE_MACH_RECV: mach port (mach_port_t) DISPATCH_SOURCE_TYPE_MEMORYPRESSURE n/a DISPATCH_SOURCE_TYPE_PROC: process identifier (pid_t) DISPATCH_SOURCE_TYPE_READ: file descriptor (int) DISPATCH_SOURCE_TYPE_SIGNAL: signal number (int) DISPATCH_SOURCE_TYPE_TIMER: n/a DISPATCH_SOURCE_TYPE_VNODE: file descriptor (int) DISPATCH_SOURCE_TYPE_WRITE: file descriptor (int)

Source

pub fn mask(self: &DispatchSource) -> usize

Returns the mask of events monitored by the dispatch source.

Parameter source: The result of passing NULL in this parameter is undefined.

Returns: The return value should be interpreted according to the type of the dispatch source, and may be one of the following flag sets:

DISPATCH_SOURCE_TYPE_DATA_ADD: n/a DISPATCH_SOURCE_TYPE_DATA_OR: n/a DISPATCH_SOURCE_TYPE_DATA_REPLACE: n/a DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t DISPATCH_SOURCE_TYPE_READ: n/a DISPATCH_SOURCE_TYPE_SIGNAL: n/a DISPATCH_SOURCE_TYPE_TIMER: dispatch_source_timer_flags_t DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t DISPATCH_SOURCE_TYPE_WRITE: n/a

Source

pub fn data(self: &DispatchSource) -> usize

Returns pending data for the dispatch source.

This function is intended to be called from within the event handler block. The result of calling this function outside of the event handler callback is undefined.

Parameter source: The result of passing NULL in this parameter is undefined.

Returns: The return value should be interpreted according to the type of the dispatch source, and may be one of the following:

DISPATCH_SOURCE_TYPE_DATA_ADD: application defined data DISPATCH_SOURCE_TYPE_DATA_OR: application defined data DISPATCH_SOURCE_TYPE_DATA_REPLACE: application defined data DISPATCH_SOURCE_TYPE_MACH_SEND: dispatch_source_mach_send_flags_t DISPATCH_SOURCE_TYPE_MACH_RECV: dispatch_source_mach_recv_flags_t DISPATCH_SOURCE_TYPE_MEMORYPRESSURE dispatch_source_memorypressure_flags_t DISPATCH_SOURCE_TYPE_PROC: dispatch_source_proc_flags_t DISPATCH_SOURCE_TYPE_READ: estimated bytes available to read DISPATCH_SOURCE_TYPE_SIGNAL: number of signals delivered since the last handler invocation DISPATCH_SOURCE_TYPE_TIMER: number of times the timer has fired since the last handler invocation DISPATCH_SOURCE_TYPE_VNODE: dispatch_source_vnode_flags_t DISPATCH_SOURCE_TYPE_WRITE: estimated buffer space available

Source

pub fn merge_data(self: &DispatchSource, value: usize)

Merges data into a dispatch source of type DISPATCH_SOURCE_TYPE_DATA_ADD, DISPATCH_SOURCE_TYPE_DATA_OR or DISPATCH_SOURCE_TYPE_DATA_REPLACE, and submits its event handler block to its target queue.

Parameter source: The result of passing NULL in this parameter is undefined.

Parameter value: The value to coalesce with the pending data using a logical OR or an ADD as specified by the dispatch source type. A value of zero has no effect and will not result in the submission of the event handler block.

Source

pub fn set_timer( self: &DispatchSource, start: DispatchTime, interval: u64, leeway: u64, )

Sets a start time, interval, and leeway value for a timer source.

Once this function returns, any pending source data accumulated for the previous timer values has been cleared; the next fire of the timer will occur at ‘start’, and every ‘interval’ nanoseconds thereafter until the timer source is canceled.

Any fire of the timer may be delayed by the system in order to improve power consumption and system performance. The upper limit to the allowable delay may be configured with the ‘leeway’ argument, the lower limit is under the control of the system.

For the initial timer fire at ‘start’, the upper limit to the allowable delay is set to ‘leeway’ nanoseconds. For the subsequent timer fires at ‘start’ + N * ‘interval’, the upper limit is MIN(‘leeway’,‘interval’/2).

The lower limit to the allowable delay may vary with process state such as visibility of application UI. If the specified timer source was created with a mask of DISPATCH_TIMER_STRICT, the system will make a best effort to strictly observe the provided ‘leeway’ value even if it is smaller than the current lower limit. Note that a minimal amount of delay is to be expected even if this flag is specified.

The ‘start’ argument also determines which clock will be used for the timer: If ‘start’ is DISPATCH_TIME_NOW or was created with dispatch_time(3), the timer is based on up time (which is obtained from mach_absolute_time() on Apple platforms). If ‘start’ was created with dispatch_walltime(3), the timer is based on gettimeofday(3).

Calling this function has no effect if the timer source has already been canceled.

Parameter start: The start time of the timer. See dispatch_time() and dispatch_walltime() for more information.

Parameter interval: The nanosecond interval for the timer. Use DISPATCH_TIME_FOREVER for a one-shot timer.

Parameter leeway: The nanosecond leeway for the timer.

Source

pub unsafe fn set_registration_handler_with_block( self: &DispatchSource, handler: dispatch_block_t, )

Source

pub fn set_registration_handler_f( self: &DispatchSource, handler: dispatch_function_t, )

Sets the registration handler function for the given dispatch source.

See dispatch_source_set_registration_handler() for more details.

Parameter source: The dispatch source to modify. The result of passing NULL in this parameter is undefined.

Parameter handler: The registration handler function to submit to the source’s target queue. The context parameter passed to the registration handler function is the current context of the dispatch source at the time the handler call is made.