Module jtrim.concurrent
Package org.jtrim2.concurrent.collections

Interface TerminableQueue<T>

Type Parameters:
T - the type of the elements of the queue
public interface TerminableQueue<T>
Defines a simple queue which can be stopped from accepting any new elements. Unlike traditional blocking queues, you can easily prevent put and take calls from waiting forever in case one side goes away.

Aside from being terminable, TerminableQueue also support removing elements from the queue without immediately allowing new elements to be added to queue instead of it (assuming the queue limits the number elements or has some other limitation on when an element can be added to it).

The ordering of the queue is completely independent.

Implementations of this queue may not support null elements.

Thread safety

Implementations of this interface are required to be safely accessible from multiple threads concurrently.

Synchronization transparency

The methods of this interface are not in general synchronization transparent, because they are explicitly wait for each other. So, extra care needs to be taken when synchronizing them, considering the actual implementation.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    clear()
    Removes all the elements from this queue.
    default boolean
    offer(T entry)
    Adds an element to this queue if possible, or returns false if the queue does not accept the new element this time.
    void
    put(CancellationToken cancelToken, T entry)
    Adds an element to this queue waiting if necessary.
    boolean
    put(CancellationToken cancelToken, T entry, long timeout, TimeUnit timeoutUnit)
    Adds an element to this queue waiting if necessary.
    void
    shutdown()
    Prevents new elements to be added to this queue, but keeps the already added elements.
    boolean
    shutdownAndTryWaitUntilEmpty(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit)
    Prevents new elements to be added to this queue, and waits until no more elements are remaining in this queue or the given timeout expires.
    void
    shutdownAndWaitUntilEmpty(CancellationToken cancelToken)
    Prevents new elements to be added to this queue, and waits until no more elements are remaining in this queue.
    default T
    take(CancellationToken cancelToken)
    Removes the current head of the queue and returns it waits until it becomes available if the queue is currently empty.
    default ReservedElementRef<T>
    takeButKeepReserved(CancellationToken cancelToken)
    Removes the current head of the queue and returns it waits until it becomes available if the queue is currently empty, but keeps reserving the space for the removed element until the returned element is released.
    default T
    tryTake()
    Removes the current head of the queue and returns it, or returns null if the queue is currently empty.
    default T
    tryTake(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit)
    Removes the current head of the queue and returns it waiting the given timeout if the queue is currently empty.
    default ReservedElementRef<T>
    tryTakeButKeepReserved()
    Removes the current head of the queue and returns it, but keeps reserving the space for the removed element until the returned element is released; or returns null if the queue is currently empty.
    ReservedElementRef<T>
    tryTakeButKeepReserved(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit)
    Removes the current head of the queue and returns it waiting the given the time if necessary, but keeps reserving the space for the removed element until the returned element is released; or returns null if the timeout elapses before any element could have been retrieved.

  • Method Details

    • put

      void put(CancellationToken cancelToken, T entry) throws TerminatedQueueException
      Adds an element to this queue waiting if necessary. This method will wait until any of the following conditions are met:
      • The given element is added to this queue.
      • The given cancelToken signals cancellation before the element could have been added/
      • This queue was shut down.
      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      entry - the new element to be added to this queue. This argument cannot be null.
      Throws:
      TerminatedQueueException - thrown if adding the element was canceled, because this queue was shut down. If this exception is thrown, then it is guaranteed that the entry was not added to this queue.
      OperationCanceledException - thrown if cancellation request was detected before the element could have been added to this queue. If this exception is thrown, then it is guaranteed that the entry was not added to this queue. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • put

      boolean put(CancellationToken cancelToken, T entry, long timeout, TimeUnit timeoutUnit) throws TerminatedQueueException
      Adds an element to this queue waiting if necessary. This method will wait until any of the following conditions are met:
      • The given element is added to this queue.
      • The given timeout was reached before the element could have been added.
      • The given cancelToken signals cancellation before the element could have been added.
      • This queue was shut down.

      Note: If the element can be added right away without waiting, then it will be added regardless how low the timeout is. That is, there is no risk of failing due to timeout compared to the offer method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      entry - the new element to be added to this queue. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit to add the given element to the queue. A best effort is made to honor the given timeout, but there is no strong guarantee on the accuracy. This argument must be greater than or equal to zero.
      timeoutUnit - the time unit in which the timeout argument is to be interpreted. This argument cannot be null.
      Returns:
      true if the element was added to this queue, false if the given timeout elapsed before it could have been added.
      Throws:
      TerminatedQueueException - thrown if adding the element was canceled, because this queue was shut down. If this exception is thrown, then it is guaranteed that the entry was not added to this queue.
      OperationCanceledException - thrown if cancellation request was detected before the element could have been added to this queue. If this exception is thrown, then it is guaranteed that the entry was not added to this queue. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • offer

      default boolean offer(T entry) throws TerminatedQueueException
      Adds an element to this queue if possible, or returns false if the queue does not accept the new element this time. This method never blocks, if it can't add the element, then it returns immediately.

      This method is synchronization transparent, therefore it can be used in any context safely.

      Default implementation: The default implementation completely relies on the put(CancellationToken, T, long, TimeUnit) method.

      Parameters:
      entry - the new element to be added to this queue. This argument cannot be null.
      Returns:
      true if the element was successfully added, false if it was not added
      Throws:
      TerminatedQueueException - thrown if adding the element was canceled, because this queue was shut down. If this exception is thrown, then it is guaranteed that the entry was not added to this queue.

    • tryTakeButKeepReserved

      ReservedElementRef<T> tryTakeButKeepReserved(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit) throws TerminatedQueueException
      Removes the current head of the queue and returns it waiting the given the time if necessary, but keeps reserving the space for the removed element until the returned element is released; or returns null if the timeout elapses before any element could have been retrieved. That is, not releasing the returned will make attempting to add new elements to this queue, as if the element was not removed. However, removing a new element will return the next element, and won't return the currently returned element again.

      This method will wait until any of the following conditions are met:

      • The head was removed from this queue.
      • The given timeout was reached before the head could have been retrieved.
      • The given cancelToken signals cancellation before the head could have been removed.
      • This queue was shut down and no new elements will be allowed to be added to this list.

      Note: If the head is available right away without waiting, then it will be removed regardless how low the timeout is. That is, there is no risk of failing due to timeout compared to the tryTakeButKeepReserved() method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit to remove the head of the queue. A best effort is made to honor the given timeout, but there is no strong guarantee on the accuracy. This argument must be greater than or equal to zero.
      timeoutUnit - the time unit in which the timeout argument is to be interpreted. This argument cannot be null.
      Returns:
      the reference to the now removed head of the queue, or null if the timeout elapsed before any element could have been removed
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.
      OperationCanceledException - thrown if cancellation request was detected before an element could have been removed from this queue. If this exception is thrown, then it is guaranteed that this queue was not modified by this method. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • tryTakeButKeepReserved

      default ReservedElementRef<T> tryTakeButKeepReserved() throws TerminatedQueueException
      Removes the current head of the queue and returns it, but keeps reserving the space for the removed element until the returned element is released; or returns null if the queue is currently empty. That is, not releasing the returned will make attempting to add new elements to this queue, as if the element was not removed. However, removing a new element will return the next element, and won't return the currently returned element again.

      This method never blocks, and if the queue is currently empty, this method will returns immediately.

      This method is synchronization transparent, therefore it can be used in any context safely.

      Default implementation: The default implementation completely relies on the tryTakeButKeepReserved(CancellationToken, long, TimeUnit) method.

      Returns:
      the reference to head of the queue, or null if this queue was empty
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.

    • tryTake

      default T tryTake() throws TerminatedQueueException
      Removes the current head of the queue and returns it, or returns null if the queue is currently empty. This method immediately releases the space the returned element takes up in the queue.

      This method never blocks, and if the queue is currently empty, this method will return immediately.

      This method is synchronization transparent, therefore it can be used in any context safely.

      Default implementation: The default implementation completely relies on the tryTakeButKeepReserved() method.

      Returns:
      the head element removed from this queue, or null if this queue was empty
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.

    • tryTake

      default T tryTake(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit) throws TerminatedQueueException
      Removes the current head of the queue and returns it waiting the given timeout if the queue is currently empty. If the queue is empty even after the specified timeout elapses, this method will return null. This method immediately releases the space the returned element takes up in the queue.

      This method will wait until any of the following conditions are met:

      • The head was removed from this queue.
      • The given timeout was reached before the head could have been retrieved.
      • The given cancelToken signals cancellation before the head could have been removed.
      • This queue was shut down and no new elements will be allowed to be added to this list.

      Default implementation: The default implementation completely relies on the tryTakeButKeepReserved(CancellationToken, long, TimeUnit) method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit to remove the head of the queue. A best effort is made to honor the given timeout, but there is no strong guarantee on the accuracy. This argument must be greater than or equal to zero.
      timeoutUnit - the time unit in which the timeout argument is to be interpreted. This argument cannot be null.
      Returns:
      the head element removed from this queue, or null if this queue was empty and the given timeout elapsed
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.
      OperationCanceledException - thrown if cancellation request was detected before an element could have been removed from this queue. If this exception is thrown, then it is guaranteed that this queue was not modified by this method. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • takeButKeepReserved

      default ReservedElementRef<T> takeButKeepReserved(CancellationToken cancelToken) throws TerminatedQueueException
      Removes the current head of the queue and returns it waits until it becomes available if the queue is currently empty, but keeps reserving the space for the removed element until the returned element is released. That is, not releasing the returned will make attempting to add new elements to this queue, as if the element was not removed. However, removing a new element will return the next element, and won't return the currently returned element again.

      This method will wait until any of the following conditions are met:

      • The head was removed from this queue.
      • The given cancelToken signals cancellation before the head could have been removed.
      • This queue was shut down and no new elements will be allowed to be added to this list.

      Default implementation: The default implementation completely relies on the tryTakeButKeepReserved(CancellationToken, long, TimeUnit) method. That is, the default implementation loop on tryTakeButKeepReserved, until it returns a non-null object.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      Returns:
      the reference to the now removed head of the queue. This method never returns null.
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.
      OperationCanceledException - thrown if cancellation request was detected before an element could have been removed from this queue. If this exception is thrown, then it is guaranteed that this queue was not modified by this method. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • take

      default T take(CancellationToken cancelToken) throws TerminatedQueueException
      Removes the current head of the queue and returns it waits until it becomes available if the queue is currently empty. This method immediately releases the space the returned element takes up in the queue.

      This method will wait until any of the following conditions are met:

      • The head was removed from this queue.
      • The given cancelToken signals cancellation before the head could have been removed.
      • This queue was shut down and no new elements will be allowed to be added to this list.

      Default implementation: The default implementation completely relies on the takeButKeepReserved(CancellationToken) method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness of the cancellation. This argument cannot be null.
      Returns:
      the head element removed from this queue. This method never returns null.
      Throws:
      TerminatedQueueException - thrown if this queue was shut down, and is empty. Throwing this exception guarantees that this queue is empty, and that it will stay empty forever. Note that this queue is empty only in the sense that no more elements can be removed from it. That is, there is no guarantee that all elements were already released.
      OperationCanceledException - thrown if cancellation request was detected before an element could have been removed from this queue. If this exception is thrown, then it is guaranteed that this queue was not modified by this method. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.

    • clear

      default void clear()
      Removes all the elements from this queue. Note that reservations might still remain after this call.

      Note: If for all element addition happens-before calling this clear method, then it is guaranteed that the queue is empty after the call. However, you can't have guarantee about the state of the queue.

      The default implementation calls tryTake() until it returns null or throws a TerminatedQueueException.

    • shutdown

      void shutdown()
      Prevents new elements to be added to this queue, but keeps the already added elements. If shutdown happens-before an element addition method to this queue, then adding the element is guaranteed to fail with a TerminatedQueueException. If there is no happens-before relationship between the shutdown call and the element addition call, then the element is either added to this queue or a TerminatedQueueException is thrown, but not both.

      Note however, that already added element can still be removed from the queue as if this method has not been called until this queue becomes empty. Once this queue is empty, element removals will also keep failing with a TerminatedQueueException, meaning that the queue will remain entry from there on. In other words: If a TerminatedQueueException thrown by a method of this queue happens-before an attempt at removing or adding an element to this queue, then it is guaranteed that the attempted method call will also throw a TerminatedQueueException.

      This method is idempotent. That is, calling it multiple times have the same effect as calling it once.

    • shutdownAndWaitUntilEmpty

      void shutdownAndWaitUntilEmpty(CancellationToken cancelToken)
      Prevents new elements to be added to this queue, and waits until no more elements are remaining in this queue. This method waits until the elements are not just removed, but also released. That is, this method call is not equivalent to calling shutdown and then looping on take until a TerminatedQueueException is thrown, because this method also waits for references to be released, while TerminatedQueueException is thrown when this queue will not have any more elements to be removed.

      If this method returns normally, then it is guaranteed that a second attempt to call this method will return immediately.

      Note: It is explicitly allowed to call shutdown before this method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness
      Throws:
      OperationCanceledException - thrown if cancellation request was detected. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.
      See Also:

    • shutdownAndTryWaitUntilEmpty

      boolean shutdownAndTryWaitUntilEmpty(CancellationToken cancelToken, long timeout, TimeUnit timeoutUnit)
      Prevents new elements to be added to this queue, and waits until no more elements are remaining in this queue or the given timeout expires. This method waits until the elements are not just removed, but also released. That is, this method call is not equivalent to calling shutdown and then looping on take until a TerminatedQueueException is thrown, because this method also waits for references to be released, while TerminatedQueueException is thrown when this queue will not have any more elements to be removed.

      If this method returns true, then it is guaranteed that a second attempt to call this method will return immediately (returning true.

      Note: It is explicitly allowed to call shutdown before this method.

      Parameters:
      cancelToken - the CancellationToken which is checked if the wait should be abandoned. It is guaranteed, that if cancellation was requested, then this method will not wait forever. However, there is no stronger guarantee on the timeliness
      timeout - the maximum time to wait in the given time unit to wait for this queue to become empty. A best effort is made to honor the given timeout, but there is no strong guarantee on the accuracy. This argument must be greater than or equal to zero.
      timeoutUnit - the time unit in which the timeout argument is to be interpreted. This argument cannot be null.
      Returns:
      true if this queue is now empty, false if the given timeout elapsed before this queue was detected to become empty.
      Throws:
      OperationCanceledException - thrown if cancellation request was detected. Note however that there is no guarantee that this exception is thrown even if the token was canceled before calling this method.
      See Also: