TransferQueue Interface in Java

The TransferQueue interface is a member of the Java Collections Framework. It was introduced in JDK 1.7, it belongs to java.util.concurrent package. The TransferQueue is a BlockingQueue in which a sending thread(producer) may wait for the receiving thread(consumers) to receive elements. TransferQueue is used in message-passing applications. There are two aspects in which the message will be passed from Producer thread to Consumer thread.

• put(E e): This method is used if the producer wants to enqueue elements without waiting for a consumer. However, it waits till the space becomes available if the queue is full.
• transfer(E e): This method is generally used to transfer an element to a thread that is waiting to receive it, if there is no thread waiting then it will wait till a thread comes to the waiting state as soon as the waiting thread arrives element will be transferred into it.

A TransferQueue may also be queried, via hasWaitingConsumer(), whether there are any threads waiting for items, which is a converse analogy to a peek operation.

Declaration

public interface TransferQueue<E> extends BlockingQueue<E>

Here, E is the type of elements stored in the collection.

The Hierarchy of TransferQueue

It extends BlockingQueue<E>, Collection<E>, Iterable<E>, Queue<E> interfaces.

Example:

Java

// Java Program Demonstrate TransferQueue

import java.util.concurrent.*;
import java.util.*;

public class TransferQueueDemo {
    public static void main(String[] args)
        throws InterruptedException
    {
        // create object of TransferQueue
        // using LinkedTransferQueue() constructor
        TransferQueue<Integer> TQ
            = new LinkedTransferQueue<Integer>();

        // Add numbers to end of queue
        TQ.add(7855642);
        TQ.add(35658786);
        TQ.add(5278367);
        TQ.add(74381793);

        // print Queue
        System.out.println("Queue1: " + TQ);

        // create object of TransferQueue
        // using LinkedTransferQueue(Collection c)
        // constructor
        TransferQueue<Integer> TQ2
            = new LinkedTransferQueue<Integer>(TQ);

        // print Queue
        System.out.println("Queue2: " + TQ2);
    }
}

Output

Queue1: [7855642, 35658786, 5278367, 74381793]
Queue2: [7855642, 35658786, 5278367, 74381793]

Implementing Classes

The TransferQueue has one Implementing class which is LinkedTransferQueue. The LinkedTransferQueue is an unbounded implementation of TransferQueue interface based on linked nodes. The elements in the LinkedTransferQueue are ordered in FIFO order, with the head pointing to the element that has been on the Queue for the longest time and the tail pointing to the element that has been on the queue for the shortest time. 

Because of its asynchronous nature, size() traverses the entire collection, so it is not an O(1) time operation. It may also give inaccurate size if this collection is modified during the traversal. Bulk operations like addAll, removeAll, retainAll, containsAll, equals, and toArray are not guaranteed to be performed atomically. For example, an iterator operating concurrently with an addAll operation might observe only some of the added elements.

Syntax:

TransferQueue<E> objectName = new LinkedTransferQueue<E>();

Basic Operations

1. Adding Elements

The implementation of various methods is provided by LinkedTransferQueue to add or insert elements. They are add(E e), put(E e), offer(E e), transfer(E e). add, put, and offer methods do not care about other threads accessing the queue or not while transfer() waits for one or more recipient threads.

Java

// Java Program Demonstrate adding
// elements to TransferQueue

import java.util.concurrent.*;

class AddingElementsExample {
    public static void main(String[] args) throws Exception
    {

        // Initializing the queue
        TransferQueue<Integer> queue
            = new LinkedTransferQueue<Integer>();

        // Adding elements to this queue
        for (int i = 10; i <= 14; i++)
            queue.add(i);

        // Add the element using offer() method
        System.out.println("adding 15 "
            + queue.offer(15, 5, TimeUnit.SECONDS));

        // Adding elements to this queue
        for (int i = 16; i <= 20; i++)
            queue.put(i);

        // Printing the elements of the queue
        System.out.println(
            "The elements in the queue are:");
        for (Integer i : queue)
            System.out.print(i + " ");

        System.out.println();

        // create another queue to demonstrate transfer
        // method
        TransferQueue<String> g
            = new LinkedTransferQueue<String>();

        new Thread(new Runnable() {
            public void run()
            {
                try {
                    System.out.println("Transferring"
                                       + " an element");

                    // Transfer a String element
                    // using transfer() method
                    g.transfer("is a computer"
                               + " science portal.");
                    System.out.println(
                        "Element "
                        + "transfer is complete");
                }
                catch (InterruptedException e1) {
                    System.out.println(e1);
                }
                catch (NullPointerException e2) {
                    System.out.println(e2);
                }
            }
        })
            .start();

        try {

            // Get the transferred element
            System.out.println("Geeks for Geeks "
                               + g.take());
        }
        catch (Exception e) {
            System.out.println(e);
        }
    }
}

Output

adding 15 true
The elements in the queue are:
10 11 12 13 14 15 16 17 18 19 20 
Transferring an element
Element transfer is complete
Geeks for Geeks is a computer science portal.

2. Removing Elements

The remove() method implementation provided by LinkedTransferQueue is used to remove an element if it is present in this queue.

Java

// Java Program Demonstrate removing
// elements of TransferQueue

import java.util.concurrent.*;

class RemoveElementsExample {
    public static void main(String[] args)
    {
        // Initializing the queue
        TransferQueue<Integer> queue
            = new LinkedTransferQueue<Integer>();

        // Adding elements to this queue
        for (int i = 1; i <= 5; i++)
            queue.add(i);

        // Printing the elements of the queue
        System.out.println(
            "The elements in the queue are:");
        for (Integer i : queue)
            System.out.print(i + " ");

        // remove() method will remove the specified
        // element from the queue
        queue.remove(1);
        queue.remove(5);

        // Printing the elements of the queue
        System.out.println("\nRemaining elements in queue : ");
        for (Integer i : queue)
            System.out.print(i + " ");
    }
}

Output

The elements in the queue are:
1 2 3 4 5 
Remaining elements in queue : 
2 3 4

3. Iterating

The iterator() method implementation provided by LinkedTransferQueue is used to return an iterator over the elements in this queue in the proper sequence.

Java

// Java Program Demonstrate
// iterating over TransferQueue

import java.util.Iterator;
import java.util.concurrent.*;

class IteratingExample {
    public static void main(String[] args)
    {

        // Initializing the queue
        TransferQueue<String> queue
            = new LinkedTransferQueue<String>();

        // Adding elements to this queue
        queue.add("Gfg");
        queue.add("is");
        queue.add("fun!!");

        // Returns an iterator over the elements
        Iterator<String> iterator = queue.iterator();

        // Printing the elements of the queue
        while (iterator.hasNext())
            System.out.print(iterator.next() + " ");
    }
}

Output

Gfg is fun!! 

Methods of TransferQueue

METHOD	DESCRIPTION
getWaitingConsumerCount()	Returns an estimate of the number of consumers waiting to receive elements via BlockingQueue.take() or timed poll.
hasWaitingConsumer()	Returns true if there is at least one consumer waiting to receive an element via BlockingQueue.take() or timed poll.
transfer​(E e)	Transfers the element to a consumer, waiting if necessary to do so.
tryTransfer​(E e)	Transfers the element to a waiting consumer immediately, if possible.
tryTransfer​(E e, long timeout, TimeUnit unit)	Transfers the element to a consumer if it is possible to do so before the timeout elapses.

Methods declared in interface java.util.concurrent.BlockingQueue

METHOD	DESCRIPTION
add​(E e)	Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions, returning true upon success and throwing an IllegalStateException if no space is currently available.
contains​(Object o)	Returns true if this queue contains the specified element.
drainTo​(Collection<? super E> c)	Removes all available elements from this queue and adds them to the given collection.
drainTo​(Collection<? super E> c, int maxElements)	Removes at most the given number of available elements from this queue and adds them to the given collection.
offer​(E e)	Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions, returning true upon success and false if no space is currently available.
offer​(E e, long timeout, TimeUnit unit)	Inserts the specified element into this queue, waiting up to the specified wait time if necessary for space to become available.
poll​(long timeout, TimeUnit unit)	Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.
put​(E e)	Inserts the specified element into this queue, waiting if necessary for space to become available.
remainingCapacity()	Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer.MAX_VALUE if there is no intrinsic limit.
remove​(Object o)	Removes a single instance of the specified element from this queue, if it is present.
take()	Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Methods declared in interface java.util.Collection

METHOD	DESCRIPTION
addAll​(Collection<? extends E> c)	Adds all of the elements in the specified collection to this collection (optional operation).
clear()	Removes all of the elements from this collection (optional operation).
containsAll​(Collection<?> c)	Returns true if this collection contains all of the elements in the specified collection.
equals​(Object o)	Compares the specified object with this collection for equality.
hashCode()	Returns the hash code value for this collection.
isEmpty()	Returns true if this collection contains no elements.
iterator()	Returns an iterator over the elements in this collection.
parallelStream()	Returns a possibly parallel Stream with this collection as its source.
removeAll​(Collection<?> c)	Removes all of this collection’s elements that are also contained in the specified collection (optional operation).
removeIf​(Predicate<? super E> filter)	Removes all of the elements of this collection that satisfy the given predicate.
retainAll​(Collection<?> c)	Retains only the elements in this collection that are contained in the specified collection (optional operation).
size()	Returns the number of elements in this collection.
spliterator()	Creates a Spliterator over the elements in this collection.
stream()	Returns a sequential Stream with this collection as its source.
toArray()	Returns an array containing all of the elements in this collection.
toArray​(IntFunction<T[]> generator)	Returns an array containing all of the elements in this collection, using the provided generator function to allocate the returned array.
toArray​(T[] a)	Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.

Methods declared in interface java.lang.Iterable

METHOD	DESCRIPTION
forEach​(Consumer<? super T> action)	Performs the given action for each element of the Iterable until all elements have been processed or the action throws an exception.

Methods declared in interface java.util.Queue

METHOD	DESCRIPTION
element()	Retrieves, but does not remove, the head of this queue.
peek()	Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
poll()	Retrieves and removes the head of this queue, or returns null if this queue is empty.
remove()	Retrieves and removes the head of this queue.

Reference: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/TransferQueue.html