Guide to the Java TransferQueue

1. Overview

In this article, we’ll be looking at the TransferQueue construct from the standard java.util.concurrent package.

Simply put, this queue allows us to create programs according to the producer-consumer pattern, and coordinate messages passing from producers to consumers.

The implementation is actually similar to the BlockingQueue – but gives us the new ability to implement a form of backpressure. This means that, when the producer sends a message to the consumer using the transfer() method, the producer will stay blocked until the message is consumed.

2. One Producer – Zero Consumers

Let’s test a transfer() method from the TransferQueue – the expected behavior is that the producer will be blocked until the consumer receives the message from the queue using a take() method.

To achieve that, we’ll create a program that has one producer but zero consumers. The first call of transfer() from the producer thread will block indefinitely, as we don’t have any consumers to fetch that element from the queue.

Let’s see how the Producer class looks like:

class Producer implements Runnable {
    private TransferQueue<String> transferQueue;
 
    private String name;
 
    private Integer numberOfMessagesToProduce;
 
    public AtomicInteger numberOfProducedMessages
      = new AtomicInteger();

    @Override
    public void run() {
        for (int i = 0; i < numberOfMessagesToProduce; i++) {
            try {
                boolean added 
                  = transferQueue.tryTransfer("A" + i, 4000, TimeUnit.MILLISECONDS);
                if(added){
                    numberOfProducedMessages.incrementAndGet();
                }
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }
    // standard constructors
}

We are passing an instance of the TransferQueue to the constructor together with a name that we want to give our producer and the number of elements that should be transferred to the queue.

Note that we are using the tryTransfer() method, with a given timeout. We are waiting four seconds, and if a producer is not able to transfer the message within the given timeout, it returns false and moves on to the next message. The producer has a numberOfProducedMessages variable to keep track of how many messages were produced.

Next, let’s look at the Consumer class:

class Consumer implements Runnable {
 
    private TransferQueue<String> transferQueue;
 
    private String name;
 
    private int numberOfMessagesToConsume;
 
    public AtomicInteger numberOfConsumedMessages
     = new AtomicInteger();

    @Override
    public void run() {
        for (int i = 0; i < numberOfMessagesToConsume; i++) {
            try {
                String element = transferQueue.take();
                longProcessing(element);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }

    private void longProcessing(String element)
      throws InterruptedException {
        numberOfConsumedMessages.incrementAndGet();
        Thread.sleep(500);
    }
    
    // standard constructors
}

It is similar to the producer, but we are receiving elements from the queue by using the take() method. We are also simulating some long running action by using the longProcessing() method in which we are incrementing the numberOfConsumedMessages variable that is a counter of the received messages.

Now, let’s start our program with only one producer:

@Test
public void whenUseOneProducerAndNoConsumers_thenShouldFailWithTimeout() 
  throws InterruptedException {
    // given
    TransferQueue<String> transferQueue = new LinkedTransferQueue<>();
    ExecutorService exService = Executors.newFixedThreadPool(2);
    Producer producer = new Producer(transferQueue, "1", 3);

    // when
    exService.execute(producer);

    // then
    exService.awaitTermination(5000, TimeUnit.MILLISECONDS);
    exService.shutdown();

    assertEquals(producer.numberOfProducedMessages.intValue(), 0);
}

We want to send three elements to the queue, but the producer is blocked on the first element, and there is no consumer to fetch that element from the queue. We are using the tryTransfer() method which will block until the message is consumed or the timeout is reached. After the timeout, it will return false to indicate the transfer has failed, and it will try to transfer the next one. This is the output from the previous example:

Producer: 1 is waiting to transfer...
can not add an element due to the timeout
Producer: 1 is waiting to transfer...

3. One Producer – One Consumer

Let’s test a situation when there are one producer and one consumer:

@Test
public void whenUseOneConsumerAndOneProducer_thenShouldProcessAllMessages() 
  throws InterruptedException {
    // given
    TransferQueue<String> transferQueue = new LinkedTransferQueue<>();
    ExecutorService exService = Executors.newFixedThreadPool(2);
    Producer producer = new Producer(transferQueue, "1", 3);
    Consumer consumer = new Consumer(transferQueue, "1", 3);

    // when
    exService.execute(producer);
    exService.execute(consumer);

    // then
    exService.awaitTermination(5000, TimeUnit.MILLISECONDS);
    exService.shutdown();

    assertEquals(producer.numberOfProducedMessages.intValue(), 3);
    assertEquals(consumer.numberOfConsumedMessages.intValue(), 3);
}

The TransferQueue is used as an exchange point, and until the consumer consumes an element from the queue, the producer cannot proceed with adding another element to it. Let’s look at the program output:

Producer: 1 is waiting to transfer...
Consumer: 1 is waiting to take element...
Producer: 1 transferred element: A0
Producer: 1 is waiting to transfer...
Consumer: 1 received element: A0
Consumer: 1 is waiting to take element...
Producer: 1 transferred element: A1
Producer: 1 is waiting to transfer...
Consumer: 1 received element: A1
Consumer: 1 is waiting to take element...
Producer: 1 transferred element: A2
Consumer: 1 received element: A2

We see that producing and consuming elements from the queue is sequential because of the specification of TransferQueue.

4. Many Producers – Many Consumers

In the last example we will consider having multiple consumers and multiple producers:

@Test
public void whenMultipleConsumersAndProducers_thenProcessAllMessages() 
  throws InterruptedException {
    // given
    TransferQueue<String> transferQueue = new LinkedTransferQueue<>();
    ExecutorService exService = Executors.newFixedThreadPool(3);
    Producer producer1 = new Producer(transferQueue, "1", 3);
    Producer producer2 = new Producer(transferQueue, "2", 3);
    Consumer consumer1 = new Consumer(transferQueue, "1", 3);
    Consumer consumer2 = new Consumer(transferQueue, "2", 3);

    // when
    exService.execute(producer1);
    exService.execute(producer2);
    exService.execute(consumer1);
    exService.execute(consumer2);

    // then
    exService.awaitTermination(10_000, TimeUnit.MILLISECONDS);
    exService.shutdown();

    assertEquals(producer1.numberOfProducedMessages.intValue(), 3);
    assertEquals(producer2.numberOfProducedMessages.intValue(), 3);
}

In this example, we have two consumers and two producers. When the program starts, we see that both producers can produce one element and after that, they will block until one of the consumers takes that element from the queue:

Producer: 1 is waiting to transfer...
Consumer: 1 is waiting to take element...
Producer: 2 is waiting to transfer...
Producer: 1 transferred element: A0
Producer: 1 is waiting to transfer...
Consumer: 1 received element: A0
Consumer: 1 is waiting to take element...
Producer: 2 transferred element: A0
Producer: 2 is waiting to transfer...
Consumer: 1 received element: A0
Consumer: 1 is waiting to take element...
Producer: 1 transferred element: A1
Producer: 1 is waiting to transfer...
Consumer: 1 received element: A1
Consumer: 2 is waiting to take element...
Producer: 2 transferred element: A1
Producer: 2 is waiting to transfer...
Consumer: 2 received element: A1
Consumer: 2 is waiting to take element...
Producer: 1 transferred element: A2
Consumer: 2 received element: A2
Consumer: 2 is waiting to take element...
Producer: 2 transferred element: A2
Consumer: 2 received element: A2

5. Conclusion

In this article, we were looking at the TransferQueue construct from the java.util.concurrent package.

We saw how to implement the producer-consumer program using that construct. We used a transfer() method to create a form of backpressure, where a producer can not publish another element until the consumer retrieves an element from the queue.

The TransferQueue can be very useful when we do not want an over-producing producer that will flood the queue with messages, resulting in the OutOfMemory errors. In such design, the consumer will be dictating the speed at which the producer will produce messages.