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}