001/** 002 * Copyright (c) 2008-2009 Apple Inc. All rights reserved. 003 * Copyright (C) 2012 FuseSource, Inc. 004 * http://fusesource.com 005 * 006 * Licensed under the Apache License, Version 2.0 (the "License"); 007 * you may not use this file except in compliance with the License. 008 * You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 019package org.fusesource.hawtdispatch; 020 021/** 022 * <p> 023 * A dispatch source is used to monitor low-level system objects and 024 * automatically submit a handler runnable to a dispatch queue in response 025 * to events. 026 * </p><p> 027 * Dispatch sources are not reentrant. Any events received while the dispatch 028 * source is suspended or while the event handler runnable is currently executing 029 * will be coalesced and delivered after the dispatch source is resumed or the 030 * event handler runnable has returned. 031 * </p><p> 032 * Dispatch sources are created in a suspended state. After creating the 033 * source and setting any desired attributes (i.e. the handlers), 034 * a call must be made to the dispatch source's <code>resume()</code> method 035 * in order to begin event delivery. 036 * </p> 037 * 038 * @author <a href="http://hiramchirino.com">Hiram Chirino</a> 039 */ 040public interface DispatchSource extends DispatchObject { 041 042 /** 043 * <p> 044 * Sets the cancellation handler runnable for the given dispatch source. 045 * </p><p> 046 * The cancellation handler (if specified) will be submitted to the source's 047 * target queue in response to a call to {@link #cancel()} once the 048 * system has released all references to the source's underlying handle and 049 * the source's event handler runnable has returned. 050 * </p> 051 * 052 * @param handler 053 * The cancellation handler runnable to submit to the source's target queue. 054 */ 055 public void setCancelHandler(Runnable handler); 056 057 /** 058 * <p> 059 * Sets the event handler runnable of this dispatch source. 060 * </p> 061 * 062 * @param handler 063 * The event handler runnable to submit to the source's target queue. 064 */ 065 public void setEventHandler(Runnable handler); 066 067 /** 068 * <p> 069 * Sets the cancellation handler task for the given dispatch source. 070 * </p><p> 071 * The cancellation handler (if specified) will be submitted to the source's 072 * target queue in response to a call to {@link #cancel()} once the 073 * system has released all references to the source's underlying handle and 074 * the source's event handler runnable has returned. 075 * </p> 076 * 077 * @param task 078 * The cancellation handler runnable to submit to the source's target queue. 079 */ 080 public void setCancelHandler(Task task); 081 082 /** 083 * <p> 084 * Sets the event handler task of this dispatch source. 085 * </p> 086 * 087 * @param task 088 * The event handler runnable to submit to the source's target queue. 089 */ 090 public void setEventHandler(Task task); 091 092 /** 093 * <p> 094 * Asynchronously cancel the dispatch source, preventing any further invocation 095 * of its event handler runnable. 096 * </p><p> 097 * Cancellation prevents any further invocation of the event handler runnable for 098 * the specified dispatch source, but does not interrupt an event handler 099 * runnable that is already in progress. 100 * </p><p> 101 * The cancellation handler is submitted to the source's target queue once the 102 * the source's event handler has finished, indicating it is now safe to close 103 * the source's handle. 104 * </p> 105 * 106 * @see #setCancelHandler(Runnable) 107 */ 108 public void cancel(); 109 110 /** 111 * @see #cancel() 112 * @return true if the dispatch source has been canceled. 113 */ 114 public boolean isCanceled(); 115 116}