From c558489e0a7869333cf2109d1a139d4337c84176 Mon Sep 17 00:00:00 2001 From: John Cairns Date: Mon, 22 Feb 2016 11:14:35 -0600 Subject: [PATCH] Version 1.2.2-SNAPSHOT pre-release --- .../util/collection/FixedStack.java | 193 ++++++++++-------- .../util/collection/Stack.java | 18 +- .../util/concurrent/BlockingStack.java | 5 + .../util/concurrent/ConcurrentStack.java | 2 +- .../util/concurrent/OptimisticLock.java | 8 +- .../util/estimation/Percentile.java | 2 +- 6 files changed, 127 insertions(+), 101 deletions(-) diff --git a/src/main/java/com/conversantmedia/util/collection/FixedStack.java b/src/main/java/com/conversantmedia/util/collection/FixedStack.java index 7661c42..d6bcd24 100644 --- a/src/main/java/com/conversantmedia/util/collection/FixedStack.java +++ b/src/main/java/com/conversantmedia/util/collection/FixedStack.java @@ -1,5 +1,25 @@ package com.conversantmedia.util.collection; +/* + * #%L + * Conversant Disruptor + * ~~ + * Conversantmedia.com © 2016, Conversant, Inc. Conversant® is a trademark of Conversant, Inc. + * ~~ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * #L% + */ + /** * A very high performance stack to replace java.util.Stack. This * stack wraps around rather than checking for bounds. @@ -13,43 +33,46 @@ * * This object is not thread safe. * - * @author John Cairns Date: 7/9/12 Time: 8:53 AM + * @author John Cairns {@literal } Date: 7/9/12 Time: 8:53 AM */ public class FixedStack implements Stack { - // implement a ring buffer to make sure that it is always safe to push an object into the stack, - // if stack size is exceeded, the eldest objects are overwritten - private final int size; - private final int mask; - private final N[] stack; - // use a ring buffer to avoid object manipulation on the stack - private int stackTop; + // implement a ring buffer to make sure that it is always safe to push an object into the stack, + // if stack size is exceeded, the eldest objects are overwritten + private final int size; + private final int mask; + private final N[] stack; + // use a ring buffer to avoid object manipulation on the stack + private int stackTop; - /** - * construct a new stack of given capacity - */ - public FixedStack(final int size) { - int stackSize = 1; - while(stackSize < size) stackSize <<=1; - this.size = stackSize; - this.mask = this.size-1; - stack = (N[])new Object[stackSize]; - stackTop=0; - } + /** + * construct a new stack of given capacity + * + * @param size - the stack size + */ + public FixedStack(final int size) { + int stackSize = 1; + while(stackSize < size) stackSize <<=1; + this.size = stackSize; + this.mask = this.size-1; + stack = (N[])new Object[stackSize]; + stackTop=0; + } - /** - * add a node to the stack - * - * @param n - */ - @Override - public boolean push(final N n) { - if(stackTop < size) { - stack[(stackTop++) & mask] = n; - return true; - } - return false; + /** + * add an element to the stack + * + * @param n - the element to add + * @return boolean - true if the operation succeeded + */ + @Override + public boolean push(final N n) { + if(stackTop < size) { + stack[(stackTop++) & mask] = n; + return true; + } + return false; - } + } @Override public boolean contains(final N n) { @@ -60,65 +83,65 @@ public boolean contains(final N n) { return false; } - /** - * peek at the top of the stack - * - * @return N - the object at the top of the stack - */ - @Override - public N peek() { - return stack[(stackTop-1)&mask]; - } + /** + * peek at the top of the stack + * + * @return N - the object at the top of the stack + */ + @Override + public N peek() { + return stack[(stackTop-1)&mask]; + } - /** - * pop the next element off the stack - * @return N - The object on the top of the stack - */ - @Override - public N pop() { - try { - return stack[(--stackTop)&mask]; - } finally { - // remove the reference to the element in the - // stack to prevent hanging references from living forever - stack[(stackTop&mask)] = null; - } - } + /** + * pop the next element off the stack + * @return N - The object on the top of the stack + */ + @Override + public N pop() { + try { + return stack[(--stackTop)&mask]; + } finally { + // remove the reference to the element in the + // stack to prevent hanging references from living forever + stack[(stackTop&mask)] = null; + } + } - // return the size of the stack + // return the size of the stack - /** - * Return the size of the stack - * @return int - number of elements in the stack - */ - @Override - public int size() { - return stackTop; - } + /** + * Return the size of the stack + * @return int - number of elements in the stack + */ + @Override + public int size() { + return stackTop; + } - /** - * how much available space in the stack - */ - @Override - public int remainingCapacity() { - return size - stackTop; - } + /** + * how much available space in the stack + */ + @Override + public int remainingCapacity() { + return size - stackTop; + } - /** - * - * @return boolean - true if stack is currently empty - */ - @Override - public boolean isEmpty() { - return stackTop==0; - } + /** + * + * @return boolean - true if stack is currently empty + */ + @Override + public boolean isEmpty() { + return stackTop==0; + } - /** - * clear the stack - */ - @Override + /** + * clear the stack + */ + @Override public void clear() { - stackTop=0; - } + stackTop=0; + } } diff --git a/src/main/java/com/conversantmedia/util/collection/Stack.java b/src/main/java/com/conversantmedia/util/collection/Stack.java index 692e3df..bba718c 100644 --- a/src/main/java/com/conversantmedia/util/collection/Stack.java +++ b/src/main/java/com/conversantmedia/util/collection/Stack.java @@ -25,11 +25,10 @@ */ public interface Stack { - /** * Linear search the stack for contains - not an efficient operation * - * @param n + * @param n - Object to test for containment * @return boolean - true if n is contained somewhere in the stack */ boolean contains(N n); @@ -38,14 +37,14 @@ public interface Stack { * Add the element to the stack top, optionally failing if there is * no capacity (overflow) * - * @param n - * @return + * @param n - element to push + * @return boolean - true if push succeeded */ boolean push(N n); /** * show the current stack top - * @return + * @return N - the element at the top of the stack or null */ N peek(); @@ -57,16 +56,12 @@ public interface Stack { N pop(); /** - * return the size of the stack in number of elements - * - * @return + * @return int - the size of the stack in number of elements */ int size(); /** - * return the number of empty slots available in the stack - * - * @return + * @return int - the number of empty slots available in the stack */ int remainingCapacity(); @@ -79,4 +74,5 @@ public interface Stack { * clear the stack */ void clear(); + } diff --git a/src/main/java/com/conversantmedia/util/concurrent/BlockingStack.java b/src/main/java/com/conversantmedia/util/concurrent/BlockingStack.java index e48ccd7..afa5e76 100644 --- a/src/main/java/com/conversantmedia/util/concurrent/BlockingStack.java +++ b/src/main/java/com/conversantmedia/util/concurrent/BlockingStack.java @@ -36,6 +36,8 @@ public interface BlockingStack extends Stack { * @param time - the maximum time to wait * @param unit - unit of waiting time * @return boolean - true if item was pushed, false otherwise + * + * @throws InterruptedException on interrupt */ boolean push(final N n, final long time, final TimeUnit unit) throws InterruptedException; @@ -53,6 +55,8 @@ public interface BlockingStack extends Stack { * @param time - the maximum time to wait * @param unit - the time unit for the waiting time * @return N - the popped element, or null in the event of a timeout + * + * @throws InterruptedException on interrupt */ N pop(final long time, final TimeUnit unit) throws InterruptedException; @@ -64,4 +68,5 @@ public interface BlockingStack extends Stack { * @throws InterruptedException - in the event the current thread is interrupted prior to popping any element */ N popInterruptibly() throws InterruptedException; + } diff --git a/src/main/java/com/conversantmedia/util/concurrent/ConcurrentStack.java b/src/main/java/com/conversantmedia/util/concurrent/ConcurrentStack.java index f3ebb8b..df71b26 100644 --- a/src/main/java/com/conversantmedia/util/concurrent/ConcurrentStack.java +++ b/src/main/java/com/conversantmedia/util/concurrent/ConcurrentStack.java @@ -115,7 +115,7 @@ public boolean contains(final N n) { /** * add an element to the stack, failing if the stack is unable to grow * - * @param n + * @param n - the element to push * * @return boolean - false if stack overflow, true otherwise */ diff --git a/src/main/java/com/conversantmedia/util/concurrent/OptimisticLock.java b/src/main/java/com/conversantmedia/util/concurrent/OptimisticLock.java index d4e3fc6..7c5525a 100644 --- a/src/main/java/com/conversantmedia/util/concurrent/OptimisticLock.java +++ b/src/main/java/com/conversantmedia/util/concurrent/OptimisticLock.java @@ -18,7 +18,7 @@ public interface OptimisticLock { * check if optimistic locking succeeded * * @param lockToken - the value returned from tryLock - * @return + * @return boolean - true if lock was held */ boolean readLockHeld(long lockToken); @@ -32,7 +32,7 @@ public interface OptimisticLock { /** * @return long - the token indicating the lock state * - * @throws InterruptedException + * @throws InterruptedException - on interrupt */ long tryWriteLockInterruptibly() throws InterruptedException; @@ -43,13 +43,15 @@ public interface OptimisticLock { /** * @return long - the token indicating the lock state, or 0 if not available + * + * @throws InterruptedException on interrupt */ long tryWriteLock(long time, TimeUnit unit) throws InterruptedException; /** * "commit" or unlock the sequence when the write lock is held * - * @param sequence + * @param sequence - lock sequence to unlock */ void unlock(final long sequence); diff --git a/src/main/java/com/conversantmedia/util/estimation/Percentile.java b/src/main/java/com/conversantmedia/util/estimation/Percentile.java index c003c98..49db5c1 100644 --- a/src/main/java/com/conversantmedia/util/estimation/Percentile.java +++ b/src/main/java/com/conversantmedia/util/estimation/Percentile.java @@ -101,7 +101,7 @@ public void clear() { /** * Add a measurement to estimate * - * @param x + * @param x - the value of the measurement */ public void add(final float x) { if(isInitializing) {