Skip to content

Commit

Permalink
More doc improvement
Browse files Browse the repository at this point in the history
  • Loading branch information
@pveentjer
pveentjer committed Jan 19, 2025
1 parent 44a0485 commit a8cce93
Showing 1 changed file with 29 additions and 56 deletions.
85 changes: 29 additions & 56 deletions agrona/src/main/java/org/agrona/concurrent/status/AtomicCounter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,9 +200,7 @@ public void updateKey(final DirectBuffer keyBuffer, final int offset, final int
}

/**
* Atomic increment of the counter.
* <p>
* This method has volatile memory semantics.
* Perform an atomic increment that will not lose updates across threads.
*
* @return the previous value of the counter
*/
Expand All @@ -212,8 +210,9 @@ public long increment()
}

/**
* Perform increment that is not safe across threads; it can result into lost
* updates to race condition.
* Perform an atomic increment that is not safe across threads.
* <p>
* This method is identical to {@link #incrementRelease()} and that method should be used instead.
*
* @return the previous value of the counter
*/
Expand Down Expand Up @@ -246,7 +245,7 @@ public long incrementRelease()
}

/**
* Non-atomically increment the counter.
* Increment the counter.
* <p>
* This method is not atomic and this can lead to lost-updates due to race conditions. This load and store
* have plain memory semantics.
Expand All @@ -265,9 +264,7 @@ public long incrementPlain()
}

/**
* Atomically decrement the counter.
* <p>
* This method has volatile memory semantics.
* Perform an atomic decrement that will not lose updates across threads.
*
* @return the previous value of the counter
*/
Expand All @@ -277,9 +274,7 @@ public long decrement()
}

/**
* Perform a decrement that is not safe across threads.
* <p>
* This method is identical to {@link #decrementRelease()}.
* Perform an atomic decrement that is not safe across threads.
*
* @return the previous value of the counter
*/
Expand All @@ -289,7 +284,7 @@ public long decrementOrdered()
}

/**
* Perform a non-atomic decrement.
* Decrements the counter non-atomically.
* <p>
* It can result into lost updates to race condition when called concurrently.
* <p>
Expand All @@ -311,7 +306,7 @@ public long decrementRelease()
}

/**
* Atomically set the counter value with volatile memory semantics.
* Set the counter with volatile semantics.
*
* @param value to be set with volatile semantics.
*/
Expand All @@ -321,19 +316,19 @@ public void set(final long value)
}

/**
* Atomically set the counter value with ordered semantics.
* Set the counter with ordered semantics.
* <p>
* This method is identical to {@link #setRelease(long)}.
* This method is identical to {@link #setRelease(long)} and that method should be used instead.
*
* @param value to be set
* @param value to be set with ordered semantics.
*/
public void setOrdered(final long value)
{
setRelease(value);
}

/**
* Atomically set the counter value.
* Set the counter value atomically.
* <p>
* The store has release memory semantics.
*
Expand All @@ -345,9 +340,9 @@ public void setRelease(final long value)
}

/**
* Set the counter with plain memory semantics.
* Set the counter with normal semantics.
* <p>
* This method is identical to {@link #setPlain(long)}.
* This method is identical to {@link #setPlain(long)} and that method should be used instead.
*
* @param value to be set with normal semantics.
*/
Expand All @@ -357,9 +352,7 @@ public void setWeak(final long value)
}

/**
* Set the counter value.
* <p>
* This method has plain memory semantics.
* Set the counter value with plain memory semantics.
*
* @param value to be set with normal semantics.
*/
Expand All @@ -369,9 +362,7 @@ public void setPlain(final long value)
}

/**
* Atomically add an increment to the counter.
* <p>
* This method has volatile memory semantics.
* Add an increment to the counter that will not lose updates across threads.
*
* @param increment to be added.
* @return the previous value of the counter
Expand All @@ -382,11 +373,11 @@ public long getAndAdd(final long increment)
}

/**
* Non-atomically adds an increment to the counter with ordered store semantics.
* Add an increment to the counter with ordered store semantics.
* <p>
* This method is identical to the {@link #getAndAddRelease(long)}
* This method is identical to {@link #getAndAddRelease(long)} and that method should be used instead.
*
* @param increment to be added
* @param increment to be added with ordered store semantics.
* @return the previous value of the counter
*/
public long getAndAddOrdered(final long increment)
Expand All @@ -395,7 +386,7 @@ public long getAndAddOrdered(final long increment)
}

/**
* Non atomically add an increment to the counter.
* Adds an increment to the counter non atomically.
* <p>
* This method is not atomic; it can suffer from lost-updates due to race conditions.
* <p>
Expand All @@ -419,8 +410,6 @@ public long getAndAddRelease(final long increment)

/**
* Get the current value of a counter and atomically set it to a new value.
* <p>
* This method has volatile memory semantics.
*
* @param value to be set.
* @return the previous value of the counter
Expand All @@ -431,9 +420,7 @@ public long getAndSet(final long value)
}

/**
* Atomically Compare the current value to expected and if true then set to the update value.
* <p>
* This method has volatile memory semantics.
* Compare the current value to expected and if true then set to the update value atomically.
*
* @param expectedValue for the counter.
* @param updateValue for the counter.
Expand All @@ -445,7 +432,7 @@ public boolean compareAndSet(final long expectedValue, final long updateValue)
}

/**
* Atomically get the latest value for the counter with volatile memory semantics.
* Get the latest value for the counter with volatile semantics.
*
* @return the latest value for the counter.
*/
Expand All @@ -455,19 +442,9 @@ public long get()
}

/**
* Atomically get the latest value for the counter with acquire memory semantics.
*
* @return the latest value for the counter.
*/
public long getAcquire()
{
return UnsafeApi.getLongVolatile(byteArray, addressOffset);
}

/**
* Get the value of the counter using weak semantics. This is the same a standard read of a field.
* Get the value of the counter using weak ordering semantics. This is the same a standard read of a field.
* <p>
* This method is identical to {@link #setPlain(long)}.
* This method is identical to {@link #getPlain()} and that method should be used instead.
*
* @return the value for the counter.
*/
Expand All @@ -477,7 +454,7 @@ public long getWeak()
}

/**
* Get the value of the counter using plain semantics. This is the same a standard read of a field.
* Get the value of the counter using plain memory semantics. This is the same a standard read of a field.
*
* @return the value for the counter.
*/
Expand All @@ -487,9 +464,7 @@ public long getPlain()
}

/**
* Set the value to a new proposedValue if greater than the current value.
* <p>
* This method has plain memory semantics.
* Set the value to a new proposedValue if greater than the current value with memory ordering semantics.
*
* @param proposedValue for the new max.
* @return true if a new max as been set otherwise false.
Expand All @@ -510,11 +485,9 @@ public boolean proposeMax(final long proposedValue)
}

/**
* Set the value to a new proposedValue if greater than the current value.
* <p>
* This method has release memory semantics.
* Set the value to a new proposedValue if greater than the current value with memory ordering semantics.
* <p>
* It is identical to {@link #proposeMaxRelease(long)}.
* This method is identical to {@link #proposeMaxRelease(long)} and that method should be used instead.
*
* @param proposedValue for the new max.
* @return true if a new max as been set otherwise false.
Expand Down

0 comments on commit a8cce93

Please sign in to comment.