The java.util.concurrent.Semaphore class is a counting semaphore useful to implement throttling over a shared resource.

The code bellow shows how to force only 5 threads to run concurrently even when we have 10 threads running.

package semaphore.tests;

import java.util.Date;
import java.util.concurrent.Semaphore;

public class SemaphoreTests {

  public static void main(String[] args) {
    Semaphore semaphore = new Semaphore(5);

    for (int i = 0; i < 10; i++) {
      new Worker(semaphore).start();
    }
  }
}

class Worker extends Thread {
  private Semaphore semaphore;

  public Worker(Semaphore semaphore) {
    this.semaphore = semaphore;
  }

  @Override
  public void run() {

    while (true) {
      try {
        semaphore.acquire();

        String msg = Thread.currentThread().getName() + " - running at: "
            + new Date();

        System.out.println(msg);

        Thread.sleep(10000);

      } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        break;
      } finally {
        semaphore.release();
      }
    }
  }
}

When running such code we see the following:

Thread-3 - running at: Thu Oct 20 23:38:48 GMT-03:00 2011
Thread-1 - running at: Thu Oct 20 23:38:48 GMT-03:00 2011
Thread-0 - running at: Thu Oct 20 23:38:48 GMT-03:00 2011
Thread-5 - running at: Thu Oct 20 23:38:48 GMT-03:00 2011
Thread-4 - running at: Thu Oct 20 23:38:48 GMT-03:00 2011

Thread-1 - running at: Thu Oct 20 23:38:58 GMT-03:00 2011
Thread-5 - running at: Thu Oct 20 23:38:58 GMT-03:00 2011
Thread-0 - running at: Thu Oct 20 23:38:58 GMT-03:00 2011
Thread-4 - running at: Thu Oct 20 23:38:58 GMT-03:00 2011
Thread-7 - running at: Thu Oct 20 23:38:58 GMT-03:00 2011

Thread-2 - running at: Thu Oct 20 23:39:08 GMT-03:00 2011
Thread-6 - running at: Thu Oct 20 23:39:08 GMT-03:00 2011
Thread-4 - running at: Thu Oct 20 23:39:08 GMT-03:00 2011
Thread-0 - running at: Thu Oct 20 23:39:08 GMT-03:00 2011
Thread-7 - running at: Thu Oct 20 23:39:08 GMT-03:00 2011

Thread-6 - running at: Thu Oct 20 23:39:18 GMT-03:00 2011
Thread-2 - running at: Thu Oct 20 23:39:18 GMT-03:00 2011
Thread-4 - running at: Thu Oct 20 23:39:18 GMT-03:00 2011
Thread-9 - running at: Thu Oct 20 23:39:18 GMT-03:00 2011
Thread-7 - running at: Thu Oct 20 23:39:18 GMT-03:00 2011

Notice that five threads run concurrently, sleep for five seconds and then another five threads run concurrently again and sleep for five seconds more and so on...

If you change the number of the Semaphore's permits to, for example, two permits, you should see only two threads running concurrently, sleeping for five seconds, then two more running and so on, proving that the Semaphore is controlling the throttling.

To change the number of permits, simply change the number that the Semaphore receives in its constructor: Semaphore semaphore = new Semaphore(2); and you should see:

Thread-2 - running at: Thu Oct 20 23:54:17 GMT-03:00 2011
Thread-3 - running at: Thu Oct 20 23:54:17 GMT-03:00 2011

Thread-2 - running at: Thu Oct 20 23:54:27 GMT-03:00 2011
Thread-0 - running at: Thu Oct 20 23:54:27 GMT-03:00 2011

Thread-2 - running at: Thu Oct 20 23:54:37 GMT-03:00 2011
Thread-4 - running at: Thu Oct 20 23:54:37 GMT-03:00 2011

Thread-2 - running at: Thu Oct 20 23:54:47 GMT-03:00 2011
Thread-7 - running at: Thu Oct 20 23:54:47 GMT-03:00 2011

Thread-2 - running at: Thu Oct 20 23:54:57 GMT-03:00 2011
Thread-7 - running at: Thu Oct 20 23:54:57 GMT-03:00 2011

We’ve seen how to implement a throttling mechanism using the Semaphore Java class. On the next post I’ll show how the Semaphore class can be used to control access to a pool of resources.