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
019 package 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 */
040 public 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 }