Clarify semantics of setMaximumPermits

Signed-off-by: maddie-boisvert <maddie.boisvert@gmail.com>

redisson/src/main/java/org/redisson/RedissonPermitExpirableSemaphore.java

@@ -689,37 +689,37 @@ public class RedissonPermitExpirableSemaphore extends RedissonExpirable implemen
     }
 
     @Override
-    public boolean trySetPermits(int permits) {
-        return get(trySetPermitsAsync(permits));
+    public boolean trySetPermits(int maxPermits) {
+        return get(trySetPermitsAsync(maxPermits));
     }
 
     @Override
-    public boolean trySetMaximumPermits(int permits) {
-        return get(trySetMaximumPermitsAsync(permits));
+    public int setMaximumPermits(int maxPermits) {
+        return get(setMaximumPermitsAsync(maxPermits));
     }
 
     @Override
-    public RFuture<Boolean> trySetMaximumPermitsAsync(int permits) {
-        return commandExecutor.evalWriteAsync(getRawName(), LongCodec.INSTANCE, RedisCommands.EVAL_BOOLEAN,
+    public RFuture<Integer> setMaximumPermitsAsync(int maxPermits) {
+        return commandExecutor.evalWriteAsync(getRawName(), LongCodec.INSTANCE, RedisCommands.EVAL_INTEGER,
                 "local available = redis.call('get', KEYS[1]); " +
                 "if (available == false) then " +
                     "redis.call('set', KEYS[1], ARGV[1]); " +
                     "redis.call('publish', KEYS[2], ARGV[1]); " +
-                    "return 1;" +
+                    "return ARGV[1];" +
                 "end;" +
                 "local claimed = redis.call('zcount', KEYS[3], 0, '+inf'); " +
                 "local maximum = (claimed == false and 0 or claimed) + tonumber(available); " +
                 "if (maximum == ARGV[1]) then " +
-                    "return 1;" +
+                    "return 0;" +
                 "end;" +
                 "local delta = tonumber(ARGV[1]) - maximum; " +
                 "if (delta == 0) then " +
-                    "return 1;" +
+                    "return 0;" +
                 "end;" +
                 "redis.call('incrby', KEYS[1], delta); " +
                 "redis.call('publish', KEYS[2], ARGV[1]); " +
-                "return 1;",
-                Arrays.<Object>asList(getRawName(), getChannelName(), timeoutName), permits);
+                "return delta;",
+                Arrays.<Object>asList(getRawName(), getChannelName(), timeoutName), maxPermits);
     }
 
     @Override

redisson/src/main/java/org/redisson/api/RPermitExpirableSemaphore.java

@@ -123,7 +123,7 @@ public interface RPermitExpirableSemaphore extends RExpirable, RPermitExpirableS
     int claimedPermits();
 
     /**
-     * Tries to set number of permits.
+     * Tries to set the initial number of available permits.
      *
      * @param permits - number of permits
      * @return <code>true</code> if permits has been set successfully, otherwise <code>false</code>.  
@@ -131,12 +131,14 @@ public interface RPermitExpirableSemaphore extends RExpirable, RPermitExpirableS
     boolean trySetPermits(int permits);
 
     /**
-     * Tries to set the maximum number of permits.
+     * Sets the avaiable number of permits such that the number of claimed
+     * permits and the number of available permits is equal to the provided max value.
+     * If the number of permits has not been set yet, it will be set to the max value.
      *
      * @param permits - number of permits to use as the maximum
-     * @return <code>true</code> if permits has been set successfully, otherwise <code>false</code>.
+     * @return the number of permits that were added
      */
-    boolean trySetMaximumPermits(int permits);
+    int setMaximumPermits(int maxPermits);
 
     /**
      * Increases or decreases the number of available permits by defined value. 

redisson/src/main/java/org/redisson/api/RPermitExpirableSemaphoreAsync.java

@@ -120,7 +120,7 @@ public interface RPermitExpirableSemaphoreAsync extends RExpirableAsync {
     RFuture<Integer> claimedPermitsAsync();
 
     /**
-     * Tries to set number of permits.
+     * Tries to set number of available permits.
      *
      * @param permits - number of permits
      * @return <code>true</code> if permits has been set successfully, otherwise <code>false</code>.  
@@ -128,12 +128,14 @@ public interface RPermitExpirableSemaphoreAsync extends RExpirableAsync {
     RFuture<Boolean> trySetPermitsAsync(int permits);
 
     /**
-     * Tries to set the maximum number of permits.
+     * Sets the avaiable number of permits such that the number of claimed
+     * permits and the number of available permits is equal to the provided max value.
+     * If the number of permits has not been set yet, it will be set to the max value.
      *
      * @param permits - number of permits to use as the maximum
-     * @return <code>true</code> if permits has been set successfully, otherwise <code>false</code>.
+     * @return the number of permits that were added
      */
-    RFuture<Boolean> trySetMaximumPermitsAsync(int permits);
+    RFuture<Integer> setMaximumPermitsAsync(int maxPermits);
 
     /**
      * Increases or decreases the number of available permits by defined value. 

redisson/src/test/java/org/redisson/RedissonPermitExpirableSemaphoreTest.java

@@ -182,9 +182,9 @@ public class RedissonPermitExpirableSemaphoreTest extends BaseConcurrentTest {
     }
 
     @Test
-    public void testTrySetMaximumPermits() throws InterruptedException {
+    public void testSetMaximumPermits() throws InterruptedException {
         RPermitExpirableSemaphore s = redisson.getPermitExpirableSemaphore("test");
-        assertThat(s.trySetMaximumPermits(10)).isTrue();
+        assertThat(s.setMaximumPermits(10)).isEqualTo(10);
         assertThat(s.maximumPermits()).isEqualTo(10);
         assertThat(s.availablePermits()).isEqualTo(10);
         assertThat(s.claimedPermits()).isEqualTo(0);
@@ -196,19 +196,19 @@ public class RedissonPermitExpirableSemaphoreTest extends BaseConcurrentTest {
         assertThat(s.claimedPermits()).isEqualTo(0);
 
         // attempts to set max permits succeeds
-        assertThat(s.trySetMaximumPermits(15)).isTrue();
+        assertThat(s.setMaximumPermits(15)).isEqualTo(5);
         assertThat(s.maximumPermits()).isEqualTo(15);
         assertThat(s.availablePermits()).isEqualTo(15);
         assertThat(s.claimedPermits()).isEqualTo(0);
 
         // setting to existing value succeeds
-        assertThat(s.trySetMaximumPermits(15)).isTrue();
+        assertThat(s.setMaximumPermits(15)).isEqualTo(0);
         assertThat(s.maximumPermits()).isEqualTo(15);
         assertThat(s.availablePermits()).isEqualTo(15);
         assertThat(s.claimedPermits()).isEqualTo(0);
 
         // decreasing max permits succeeds
-        assertThat(s.trySetMaximumPermits(5)).isTrue();
+        assertThat(s.setMaximumPermits(5)).isEqualTo(-10);
         assertThat(s.maximumPermits()).isEqualTo(5);
         assertThat(s.availablePermits()).isEqualTo(5);
         assertThat(s.claimedPermits()).isEqualTo(0);
@@ -226,14 +226,14 @@ public class RedissonPermitExpirableSemaphoreTest extends BaseConcurrentTest {
         assertThat(s.claimedPermits()).isEqualTo(3);
 
         // decreasing the max to the number of claimed permits is allowed
-        assertThat(s.trySetMaximumPermits(3)).isTrue();
+        assertThat(s.setMaximumPermits(3)).isEqualTo(-2);
         assertThat(s.maximumPermits()).isEqualTo(3);
         assertThat(s.availablePermits()).isEqualTo(0);
         assertThat(s.claimedPermits()).isEqualTo(3);
 
         // decreasing the max to below the number of claimed permits is allowed
         // and results in a negative number of available permits
-        assertThat(s.trySetMaximumPermits(2)).isTrue();
+        assertThat(s.setMaximumPermits(2)).isEqualTo(-1);
         assertThat(s.maximumPermits()).isEqualTo(2);
         assertThat(s.availablePermits()).isEqualTo(-1);
         assertThat(s.claimedPermits()).isEqualTo(3);