What's the point of Semaphore.drainPermits()?

Question

public int drainPermits():

Acquires and returns all permits that are immediately available. Returns: the number of permits acquired.

Why would someone want to acquire and then immediately release all available permits from a Semaphore? If they want to see the number of available permits, why not use Semaphore.availablePermits()?

Answer 1

It doesn't release them. It acquires them all, that's all:

Semaphore s = new Semaphore(10);
System.out.println(s.availablePermits()); // 10
s.drainPermits();
System.out.println(s.availablePermits()); // 0