Java LinkedTransferQueue: wait until a consumer receives work

Last updated: 5 Oct 20265 min read

tutorial

LinkedTransferQueue can hand an item directly to a waiting consumer. Its transfer operation waits until receipt, which is different from merely enqueuing an item.

Operational contract

tryTransfer with a timeout waits up to three seconds for a consumer to receive the receipt ID, then reports success or failure. The consumer uses take. Successful transfer proves handoff to a consumer, not completion of that consumer's business work. The underlying linked queue can grow without an application cap if regular offer is used; this sample exposes only the timed handoff operation. On a timeout, the producer must decide whether to retry, persist the work, or reject it. Interruption propagates to the caller.

Failure case

A depot publisher has an urgent receipt-47 notification. A worker already waiting on take can receive it immediately. If no worker receives within three seconds, the publisher sees false and can persist the notification for later delivery instead of silently treating it as processed.

Java code

import java.util.concurrent.LinkedTransferQueue;
import java.util.concurrent.TimeUnit;

public class ReceiptTransferLane {
    private final LinkedTransferQueue<String> handoffs = new LinkedTransferQueue<>();

    public boolean handoff(String receiptId) throws InterruptedException {
        return handoffs.tryTransfer(receiptId, 3, TimeUnit.SECONDS);
    }

    public String awaitReceipt() throws InterruptedException {
        return handoffs.take();
    }
}

Performance and ownership cost

The handoff uses constant application storage per pending producer, but waiting producers still consume thread or virtual-thread resources. The timed operation has up to three seconds of wait and scheduling overhead. This class is not a durable broker; a received item can be lost if the consumer fails before committing its work.

Common Mistakes

Do not equate consumer receipt with successful business processing.
Do not assume this unbounded queue enforces capacity.
Do not discard work silently when the timed transfer returns false.

Connected lessons

java

timed queues and handoffs

linkedtransferqueue-receipt-handoff