001package org.reactivestreams;
002
003/**
004 * A {@link Subscription} represents a one-to-one lifecycle of a {@link Subscriber} subscribing to a {@link Publisher}.
005 * <p>
006 * It can only be used once by a single {@link Subscriber}.
007 * <p>
008 * It is used to both signal desire for data and cancel demand (and allow resource cleanup).
009 *
010 */
011public interface Subscription {
012    /**
013     * No events will be sent by a {@link Publisher} until demand is signaled via this method.
014     * <p>
015     * It can be called however often and whenever needed.
016     * <p>
017     * Whatever has been requested can be sent by the {@link Publisher} so only signal demand for what can be safely handled.
018     * <p>
019     * A {@link Publisher} can send less than is requested if the stream ends but
020     * then must emit either {@link Subscriber#onError(Throwable)} or {@link Subscriber#onComplete()}.
021     * 
022     * @param n the strictly positive number of elements to requests to the upstream {@link Publisher}
023     */
024    public void request(int n);
025
026    /**
027     * Request the {@link Publisher} to stop sending data and clean up resources.
028     * <p>
029     * Data may still be sent to meet previously signalled demand after calling cancel as this request is asynchronous.
030     */
031    public void cancel();
032}