001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.modeshape.common.collection.ring;
018
019import java.util.concurrent.TimeoutException;
020
021/**
022 * Strategy that encapsulates how to wait for a {@link Pointer} to make the supplied position available.
023 */
024public interface WaitStrategy {
025
026    /**
027     * Wait for the given position to be available. It is possible for this method to return a value less than the supplied
028     * position supplied on the implementation of the {@link WaitStrategy}. A common use for this is to signal a timeout.
029     * 
030     * @param position the desired position
031     * @param pointer the main pointer from ringbuffer. Wait/notify strategies will need this as it's the only sequence that is
032     *        also notified upon update.
033     * @param dependentPointer on which to wait.
034     * @param barrier the processor is waiting on.
035     * @return the position that is available, and that may be greater than the requested position.
036     * @throws InterruptedException if the thread is interrupted.
037     * @throws TimeoutException if this blocking method times out
038     */
039    long waitFor( long position,
040                  Pointer pointer,
041                  Pointer dependentPointer,
042                  PointerBarrier barrier ) throws InterruptedException, TimeoutException;
043
044    /**
045     * Signal all components that want to be notified that the pointer has advanced.
046     */
047    void signalAllWhenBlocking();
048}