Package dev.gemfire.dtype

Interface DSemaphore

  • All Superinterfaces:
    DType
    public interface DSemaphore
extends DType
    DSemaphore is a highly-available, distributed version of the JDK's Semaphore. As such, the subset of methods attempts to provide the same semantics as the regular semaphore's does. DSemaphores are intended to be used from GemFire clients.

    Each DSemaphore is initialized with a number of permits that clients can acquire() or release(). If no permit is available the calling thread is blocked until one becomes available. Since DSemaphores are distributed, a given semaphore can be accessed across different JVM instances. As with regular semaphores, DSemaphores simply maintain a count of the permits available and no actual 'permit' objects are used. It is up to the calling application to ensure correct usage of the semaphore by ensuring that the acquired permits are also correctly released.

    DSemaphores are backed by objects stored in the GemFire cluster. In the event of a server shutdown or crash, the state of a given semaphore is maintained. Permits that are held by a client that crashes or closes its cache without releasing the permits, are retained for a period of time (default 30,000ms) before being automatically released. This allows for clients to retain their permits in situations where they may temporarily be disconnected.

    Example use: 

     ClientCache client = new ClientCacheFactory()
     .addPoolLocator("localhost", locatorPort)
     .create();

 factory = new DTypeFactory(client);
 DSemaphore semaphore = factory.createSemaphore("semi", 1);

 semaphore.initialize(1);
 semaphore.acquire();
    Note that a DSemaphore will only be initialized once. If a semaphore has already been created, subsequent calls to createSemaphore, even from different JVMs, will not adjust the number of permits.
    Implementation_Note
    Once a semaphore is created, the client will start a background thread to ping all servers indicating that it is alive. This effectively gives semaphores a 'lease' time. If the client crashes or leaves without releasing its permits, the permits will automatically be released once the lease expires. The default lease time is 30 seconds and the default ping interval is 10 seconds. These can be adjusted using the system properties dtype.dsemaphore.pendingReleaseTime and dtype.client.pingInterval respectively. Units are in milliseconds.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void acquire()
      Acquire a single permit.
      void acquire​(int permits)
      Acquire a number of permits.
      int availablePermits()
      Return the number of permits available
      void destroy()
      Destroy the semaphore.
      int drainPermits()
      Acquire all remaining permits if any are available.
      int getQueueLength()
      Return the number of callers waiting to acquire permits
      void release()
      Release a single permit.
      void release​(int permits)
      Release a number of permits.
      boolean tryAcquire()
      Non-blocking version of acquire which does not block.
      boolean tryAcquire​(int permits)
      Non-blocking version of acquire(int) which does not block.

      • Methods inherited from interface dev.gemfire.dtype.DType

        getName

    • Method Detail

      • acquire

        void acquire()
        Acquire a single permit. The caller will block until a permit becomes available. The order of acquisition, for block callers is non-deterministic. Unlike regular semaphores, there is no optional strategy for determining which waiting caller will acquire a permit.

      • acquire

        void acquire​(int permits)
        Acquire a number of permits. The caller will block until the total number of permits are available. This does not mean that the caller will accumulate and 'hold' permits until the required number is reached.
        Parameters:
        permits - the number of permits to acquire

      • release

        void release()
        Release a single permit. Callers waiting to acquire a permit will be notified and will contend to acquire the available permits.

      • release

        void release​(int permits)
        Release a number of permits. Note that a given client can release permits without necessarily having acquired those permits.
        Parameters:
        permits - the number of permits to acquire

      • tryAcquire

        boolean tryAcquire()
        Non-blocking version of acquire which does not block. Will return immediately with a boolean indicating success or failure.
        Returns:
        true if the permit was acquired, false otherwise

      • tryAcquire

        boolean tryAcquire​(int permits)
        Non-blocking version of acquire(int) which does not block. Will return immediately with a boolean indicating success or failure.
        Parameters:
        permits - the number of permits to acquire
        Returns:
        true if the permits were acquired, false otherwise

      • availablePermits

        int availablePermits()
        Return the number of permits available
        Returns:
        the number of permits available

      • getQueueLength

        int getQueueLength()
        Return the number of callers waiting to acquire permits
        Returns:
        the number of callers waiting to acquire permits

      • drainPermits

        int drainPermits()
        Acquire all remaining permits if any are available.
        Returns:
        the number of permits acquired

      • destroy

        void destroy()
        Destroy the semaphore. The method will release any backend structures. Callers waiting to acquire permits will receive a DTypeException indicating that the semaphore has been destroyed.
        Specified by:
        destroy in interface DType