Package io.github.dhruv1110.jcachex.concurrent

Class AccessBuffer<K>

java.lang.Object

io.github.dhruv1110.jcachex.concurrent.AccessBuffer<K>

Type Parameters:

K - the type of keys

public class AccessBuffer<K>
extends Object

A lock-free access buffer that records cache operations using ring buffers and write-ahead logging for high-performance concurrent access.

This implementation provides:

• Lock-Free Recording: Uses atomic operations for access tracking
• Write-Ahead Logging: Ensures operation ordering and consistency
• Batched Processing: Reduces contention through batch operations
• Backpressure Handling: Manages buffer overflow gracefully

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AccessBuffer.AccessRecord<K>	Represents a cache access operation.
static class	AccessBuffer.AccessType

Constructor Summary

Constructors

Constructor	Description
AccessBuffer(int drainThreshold, long drainIntervalNanos)	Creates a new access buffer.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears all pending accesses.
int	drainToHandler(Consumer<AccessBuffer.AccessRecord<K>> processor)	Drains the access buffer and processes all recorded accesses.
int	forceDrain(Consumer<AccessBuffer.AccessRecord<K>> processor)	Forces an immediate drain of all pending accesses.
long	getContentionLevel()	Returns the current contention level.
int	getPendingAccessCount()	Returns the current number of pending accesses.
int	getStripeCount()	Returns the number of stripes in the ring buffer.
boolean	isShutdown()	Checks if the access buffer is shut down.
boolean	needsDraining()	Checks if draining is needed.
boolean	recordAccess(K key, AccessBuffer.AccessType type, int frequency)	Records a cache access operation.
void	shutdown()	Shuts down the access buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AccessBuffer

public AccessBuffer(int drainThreshold,
                    long drainIntervalNanos)

Creates a new access buffer.

Parameters:

drainThreshold - the number of accesses that trigger a drain

drainIntervalNanos - the maximum time between drains in nanoseconds

Method Detail

recordAccess

public boolean recordAccess(K key,
                            AccessBuffer.AccessType type,
                            int frequency)

Records a cache access operation.

Parameters:

key - the cache key

type - the access type

frequency - the current frequency estimate

Returns:

true if the access was recorded

drainToHandler

public int drainToHandler(Consumer<AccessBuffer.AccessRecord<K>> processor)

Drains the access buffer and processes all recorded accesses.

Parameters:

processor - the function to process each access record

Returns:

the number of records processed

forceDrain

public int forceDrain(Consumer<AccessBuffer.AccessRecord<K>> processor)

Forces an immediate drain of all pending accesses.

Parameters:

processor - the function to process each access record

Returns:

the number of records processed

getPendingAccessCount

public int getPendingAccessCount()

Returns the current number of pending accesses.

Returns:

the number of pending accesses

getContentionLevel

public long getContentionLevel()

Returns the current contention level.

Returns:

the contention level

getStripeCount

public int getStripeCount()

Returns the number of stripes in the ring buffer.

Returns:

the stripe count

needsDraining

public boolean needsDraining()

Checks if draining is needed.

Returns:

true if draining is needed

shutdown

public void shutdown()

Shuts down the access buffer.

isShutdown

public boolean isShutdown()

Checks if the access buffer is shut down.

Returns:

true if shut down

clear

public void clear()

Clears all pending accesses.