\file Exchanger .d \brief A synchronization point at which two threads can exchange objects.

Written by Doug Lea with assistance from members of JCP JSR-166 Expert Group and released to the domain, as explained at

http:
//creativecommons.org/licenses/publicdomain Ported to D by Ben Hinkle. Email comments and bug reports to ben.hinkle@gmail.com

revision 2.0

  • class Exchanger "> Exchanger '); (Value);
    • \class Exchanger \brief A synchronization point at which two threads can exchange objects. Each thread presents some object on entry to the exchange method, and receives the object presented by the other thread on return.

    Sample Usage: Here are the highlights of a class that uses an Exchanger to swap buffers between threads so that the thread filling the buffer gets a freshly emptied one when it needs it, handing off the filled one to the thread emptying the buffer. 

       
Exchanger

!(DataBuffer) exchanger = new 
Exchanger

!(DataBuffer);
   DataBuffer initialEmptyBuffer = ... a made-up type
   DataBuffer initialFullBuffer = ...
   Thread t1 = new Thread(
     delegate int() {
       DataBuffer currentBuffer = initialEmptyBuffer;
       while (currentBuffer != null) {
         addToBuffer(currentBuffer);
         if (currentBuffer.full())
           currentBuffer = exchanger.exchange(currentBuffer);
       }
       return 0;
     });
   Thread t2 = new Thread(
     delegate int() {
       DataBuffer currentBuffer = initialFullBuffer;
       while (currentBuffer != null) {
         takeFromBuffer(currentBuffer);
         if (currentBuffer.empty())
           currentBuffer = exchanger.exchange(currentBuffer);
       }
       return 0;
     });
   t1.start();
   t2.start();
 }


  • Value item ;
    • Holder for the item being exchanged

  • int arrivalCount ;
    • Arrival count transitions from 0 to 1 to 2 then back to 0 during an exchange.

  • Value doExchange (Value x, bool timed, long nanos);
    • Main exchange function, handling the different policy variants.

  • this();
    • Create a new Exchanger.

  • Value exchange (Value x);
    • Waits for another thread to arrive at this exchange point and then transfers the given object to it, receiving its object in return.

    If another thread is already waiting at the exchange point then it is resumed for thread scheduling purposes and receives the object passed in by the current thread. The current thread returns immediately, receiving the object passed to the exchange by that other thread.

    If no other thread is already waiting at the exchange then the current thread is disabled for thread scheduling purposes and lies dormant until some other thread enters the exchange .

    \param x the object to exchange \return the object provided by the other thread.

  • Value exchange (Value x, long timeout, TimeUnit unit);
    • Waits for another thread to arrive at this exchange point (unless the specified waiting time elapses), and then transfers the given object to it, receiving its object in return.

    If another thread is already waiting at the exchange point then it is resumed for thread scheduling purposes and receives the object passed in by the current thread. The current thread returns immediately, receiving the object passed to the exchange by that other thread.

    If no other thread is already waiting at the exchange then the current thread is disabled for thread scheduling purposes and lies dormant until one of three things happens:

    • Some other thread enters the exchange ; or
    • The specified waiting time elapses.


    If the specified waiting time elapses then TimeoutException is thrown. If the time is less than or equal to zero, the method will not wait at all.

    \param x the object to exchange \param timeout the maximum time to wait \param unit the time unit of the timeout argument. \return the object provided by the other thread.

    :: page rendered by CandyDoc