Code Snapshot: Connection Borrowing Logic

Here’s a key piece of HikariCP internals when a thread tries to borrow a connection from the pool:

1
2
3
4
5
6
7
8

// ②
// Get a connection from the pool, with a timeout
final PoolEntry poolEntry = connectionBag.borrow(timeout, MILLISECONDS);

// The borrow method returns null only if it times out
if (poolEntry == null) {
  break; // We timed out... break and throw exception
}

This code attempts to borrow a connection from the internal connectionBag. If it doesn’t succeed within the specified timeout, it returns null, and the calling code exits the loop and throws an exception.

Behind the Scenes: What’s connectionBag?

The connectionBag is a custom concurrent structure used by HikariCP to manage connections. Internally, it uses a CopyOnWriteArrayList to store available PoolEntry objects.

Why Use CopyOnWriteArrayList?

CopyOnWriteArrayList is a thread-safe variant of ArrayList where all mutative operations (like add, remove) are implemented by making a fresh copy of the underlying array. It shines in situations where:

• Reads are far more frequent than writes.
• Thread safety is critical, but locking overhead must be minimized.

This fits HikariCP’s use case perfectly—connections are borrowed and returned frequently under high concurrency, and most operations are reads (checking for available connections).

What Happens During borrow()?

The borrow() method performs the following steps:

1. Iterates over the CopyOnWriteArrayList of available connections.
2. Tries to atomically claim one via compareAndSet.
3. If no connection is immediately available, it waits until:
   • A connection is returned.
   • The timeout expires.

Thanks to CopyOnWriteArrayList, multiple threads can safely iterate and borrow connections without the risk of ConcurrentModificationException or complex locking strategies.

Timeout Behavior

If no connection is available within the timeout window:

1
2
3

if (poolEntry == null) {
  break; // We timed out... break and throw exception
}

The system recognizes that it’s better to fail fast than to block indefinitely. This ensures predictability and avoids resource starvation under load.

Trade-offs of CopyOnWriteArrayList

While CopyOnWriteArrayList is great for safe, lock-free reads, it does have drawbacks:

• Writes (adds/removes) are costly since the array is copied.
• It’s not ideal if the list is modified very frequently.

In HikariCP’s case, connection availability doesn’t change every millisecond—so this trade-off is acceptable and even advantageous.

Takeaways

• CopyOnWriteArrayList plays a crucial role in enabling fast, concurrent access to connection entries in HikariCP.
• It ensures safety and performance without heavyweight synchronization.
• The timeout logic provides a safety net to prevent system hangs under high load.

Final Thoughts

This case study shows how a seemingly simple collection choice—like CopyOnWriteArrayList—can dramatically influence the performance and reliability of a high-throughput system like HikariCP. It’s a perfect example of using the right tool for the job in a multithreaded environment.

HikariCP Case Study: Understanding FAUX_LOCK

HikariCP, a high-performance JDBC connection pool, is renowned for its minimalist design and efficient concurrency handling. One of its clever optimizations is the FAUX_LOCK, a no-op (no operation) implementation of the SuspendResumeLock class. In this short case study, we’ll explore the purpose of FAUX_LOCK, its implementation, and how it leverages JIT (Just-In-Time) compilation to boost performance.

What is FAUX_LOCK?

The SuspendResumeLock class in HikariCP manages the suspension and resumption of connection acquisition, typically during pool maintenance or shutdown. The FAUX_LOCK is a static instance of SuspendResumeLock that overrides its methods—acquire, release, suspend, and resume—to do nothing:

1
2
3
4
5
6
7
8
9
10

public static final SuspendResumeLock FAUX_LOCK = new SuspendResumeLock(false) {
    @Override
    public void acquire() {}
    @Override
    public void release() {}
    @Override
    public void suspend() {}
    @Override
    public void resume() {}
};

This “fake” lock acts as a placeholder when actual locking is unnecessary, minimizing overhead in high-performance scenarios.

Why Use FAUX_LOCK?

HikariCP is designed for speed, and every cycle matters in high-throughput applications. The FAUX_LOCK is used when the pool is configured to operate without suspension or locking, specifically when allowPoolSuspension is false (the default). Its key purposes are:

1. Single-Threaded or Non-Suspended Pools: When pool suspension is disabled, there’s no need for lock operations. FAUX_LOCK eliminates synchronization overhead.
2. Simplified Code Path: Using FAUX_LOCK avoids conditional logic to check whether locking is needed, maintaining a consistent SuspendResumeLock interface.
3. Performance Optimization: By providing empty method implementations, FAUX_LOCK reduces the cost of lock operations to zero.

JIT Optimization: The Hidden Benefit

So, what’s the real advantage of this approach? When pool suspension is disabled, FAUX_LOCK provides an empty implementation, with the expectation that the JVM’s Just-In-Time (JIT) compiler will optimize it away. Each call to acquire, release, suspend, or resume is an empty method that does nothing. After the code runs multiple times, the JIT compiler may recognize these methods as no-ops and inline or eliminate them entirely.

This means that, over time, the overhead of calling these methods disappears. When acquiring a connection, the application skips the token acquisition step entirely, as the JIT-optimized code bypasses the empty method calls. This results in significant performance savings, especially in high-concurrency scenarios where connection acquisition is frequent.

When is FAUX_LOCK Used?

FAUX_LOCK is employed when allowPoolSuspension is false. In this mode, HikariCP does not support suspending the pool for tasks like shrinking or reaping idle connections. By using FAUX_LOCK, calls to lock-related methods become no-ops, allowing HikariCP to focus solely on connection management. For example, in a web application with a fixed pool size and no need for suspension, FAUX_LOCK ensures minimal overhead.

Benefits of FAUX_LOCK

• Zero Overhead: Empty methods eliminate lock-related costs, and JIT optimization may remove them entirely.
• Code Simplicity: A consistent SuspendResumeLock interface avoids complex branching logic.
• Flexibility: Supports both high-performance (with FAUX_LOCK) and maintenance-friendly modes (with a real lock).
• Performance Boost: JIT-eliminated method calls reduce connection acquisition time.

Considerations

FAUX_LOCK is ideal for performance-critical applications but unsuitable when pool suspension is needed (e.g., for dynamic resizing). Enabling allowPoolSuspension requires a real SuspendResumeLock, and misconfiguration could disrupt pool maintenance.

Conclusion

The FAUX_LOCK in HikariCP is a brilliant optimization that showcases how small design choices can yield big performance gains. By providing a no-op lock and leveraging JIT compilation to eliminate method call overhead, FAUX_LOCK ensures HikariCP remains blazingly fast in non-suspended pools. For developers, this underscores the importance of aligning HikariCP’s configuration with application requirements to unlock its full potential.

When configuring your HikariCP pool, check if allowPoolSuspension is necessary. If not, FAUX_LOCK and JIT optimization will work behind the scenes to make your application faster and more efficient.

HikariCP Case Study: Understanding the getConnection Semaphore

One of its key mechanisms for managing connections efficiently is the use of a Semaphore in the getConnection method. In this case study, we’ll dive into how HikariCP leverages Semaphore to manage database connections, ensuring thread safety and optimal resource utilization.

Background on HikariCP

HikariCP is a JDBC connection pool designed for speed and simplicity. Unlike traditional connection pools that may rely on heavy synchronization or complex locking mechanisms, HikariCP uses modern concurrency utilities from Java’s java.util.concurrent package, such as ConcurrentBag and Semaphore, to achieve low-latency connection management.

The getConnection method is the primary entry point for applications to acquire a database connection from the pool. This method must balance speed, thread safety, and resource constraints, especially under high concurrency. The use of a Semaphore in this context is critical to controlling access to the finite number of connections.

The Role of Semaphore in getConnection

In HikariCP, a Semaphore is used to limit the number of threads that can simultaneously attempt to acquire a connection from the pool. A Semaphore is a concurrency primitive that maintains a set of permits. Threads must acquire a permit to proceed, and if no permits are available, they block until one is released.

Here’s how HikariCP employs a Semaphore in the getConnection process:

1. Connection Acquisition Limit: The Semaphore is initialized with a number of permits corresponding to the maximum pool size (maximumPoolSize). This ensures that no more than the configured number of connections are ever allocated.

2. Thread Safety: When a thread calls getConnection, it must first acquire a permit from the Semaphore. This prevents excessive threads from overwhelming the pool or attempting to create new connections beyond the pool’s capacity.

3. Timeout Handling: HikariCP’s getConnection method supports a timeout parameter (connectionTimeout). If a thread cannot acquire a permit within this timeout, the Semaphore’s tryAcquire method fails, and HikariCP throws a SQLException, informing the application that no connection is available.

4. Efficient Resource Management: Once a connection is acquired or created, the thread proceeds to use it. After the connection is returned to the pool (via close), the permit is released back to the Semaphore, allowing another thread to acquire a connection.

This approach ensures that HikariCP remains both thread-safe and efficient, avoiding the overhead of traditional locking mechanisms like synchronized blocks.

Case Study: High-Concurrency Scenario

Let’s consider a real-world scenario where a web application handles thousands of concurrent requests, each requiring a database connection. Without proper concurrency control, the application could exhaust the database’s connection limit, leading to errors or crashes. Here’s how HikariCP’s Semaphore-based getConnection handles this:

Setup

• HikariCP Configuration:
  • maximumPoolSize: 20
  • connectionTimeout: 30000ms (30 seconds)
  • minimumIdle: 5
• Application: A Java-based REST API using Spring Boot, handling 1000 concurrent requests.
• Database: PostgreSQL with a maximum of 100 connections.

Observations

1. Initial State: The pool starts with 5 idle connections (as per minimumIdle). The Semaphore has 20 permits available, corresponding to maximumPoolSize.

2. Spike in Requests: When 1000 requests hit the API simultaneously, each thread calls getConnection. The Semaphore ensures that only 20 threads can proceed at a time. Other threads wait for permits to become available.

3. Connection Reuse: As threads complete their database operations and return connections to the pool, permits are released. Waiting threads acquire these permits and reuse existing connections, preventing the need to create new ones unnecessarily.

4. Timeout Behavior: If the pool is fully utilized and no connections are available within 30 seconds, threads that cannot acquire a permit receive a SQLException. This allows the application to gracefully handle overload scenarios, perhaps by retrying or returning an error to the client.

Results

• Stability: The Semaphore prevented the pool from exceeding 20 connections, avoiding overwhelming the PostgreSQL server.
• Performance: Connection reuse and efficient concurrency control minimized latency, with most requests served within milliseconds.
• Error Handling: Threads that timed out received clear exceptions, allowing the application to implement fallback logic.

Code Example

Below is a simplified view of how HikariCP’s getConnection logic might look, focusing on the Semaphore usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

import java.sql.Connection;
import java.sql.SQLException;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;

public class HikariPool {
    private final Semaphore connectionSemaphore;
    private final int maxPoolSize;
    private final long connectionTimeout;

    public HikariPool(int maxPoolSize, long connectionTimeoutMs) {
        this.maxPoolSize = maxPoolSize;
        this.connectionTimeout = connectionTimeoutMs;
        this.connectionSemaphore = new Semaphore(maxPoolSize, true);
    }

    public Connection getConnection() throws SQLException {
        try {
            // Attempt to acquire a permit within the timeout
            if (!connectionSemaphore.tryAcquire(connectionTimeout, TimeUnit.MILLISECONDS)) {
                throw new SQLException("Connection timeout after " + connectionTimeout + "ms");
            }
            // Logic to acquire or create a connection from the pool
            return acquireConnection();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new SQLException("Interrupted while waiting for connection", e);
        } finally {
            // Release the permit back to the semaphore after returning the connection
            connectionSemaphore.release();
        }
    }

    private Connection acquireConnection() {
        // Placeholder for actual connection acquisition logic
        return null;
    }
}

This example illustrates the Semaphore’s role in controlling access to the connection pool. In the actual HikariCP implementation, additional optimizations like the ConcurrentBag for connection storage and housekeeping threads for pool maintenance further enhance performance.

Advantages of Using Semaphore

• Lightweight Concurrency: Compared to traditional locks, Semaphore provides a more flexible and lightweight mechanism for controlling access.
• Fairness: HikariCP’s Semaphore is configured to be fair, ensuring that threads are served in the order they request permits, reducing starvation.
• Timeout Support: The ability to specify a timeout for permit acquisition aligns with HikariCP’s focus on predictable behavior under load.
• Scalability: The Semaphore scales well under high concurrency, allowing HikariCP to handle thousands of requests efficiently.

Challenges and Considerations

While the Semaphore-based approach is highly effective, there are some considerations:

1. Configuration Tuning: The maximumPoolSize and connectionTimeout must be carefully tuned based on the application’s workload and the database’s capacity. Setting maximumPoolSize too high can overwhelm the database, while setting it too low can lead to timeouts.

2. Timeout Handling: Applications must be prepared to handle SQLExceptions caused by timeouts, possibly with retry logic or user-friendly error messages.

3. Monitoring: Under high load, monitoring the pool’s metrics (e.g., active connections, wait time) is crucial to detect bottlenecks or misconfigurations.

Conclusion

HikariCP’s use of a Semaphore in the getConnection method is a brilliant example of leveraging Java’s concurrency utilities to build a high-performance connection pool. By limiting concurrent access to connections, enforcing timeouts, and ensuring thread safety, the Semaphore enables HikariCP to deliver reliable and efficient database access in demanding environments.

For developers and architects, understanding this mechanism provides valuable insights into designing scalable systems. Properly configuring HikariCP and monitoring its behavior can make the difference between a sluggish application and one that performs flawlessly under pressure.

If you’re using HikariCP in your projects, take the time to review your pool configuration and consider how the Semaphore-based concurrency control impacts your application’s performance. With the right setup, HikariCP can be a game-changer for your database-driven applications.

HikariCP Source Code Analysis: HikariPool Initialization

HikariCP is a high-performance JDBC connection pool framework, and one of its core components is the HikariPool class. This article dives into the initialization process of HikariPool, focusing on the following line of code:

1

pool = fastPathPool = new HikariPool(this);

This line appears in the initialization flow of HikariDataSource or related configuration logic, serving as a critical step in creating the HikariCP connection pool. Below, we’ll analyze its meaning, context, and implementation details from the source code perspective.

1. Context: Background of HikariPool Creation

In HikariCP, HikariPool is the core class responsible for managing database connections, including their creation, recycling, borrowing, and destruction. When an application starts and configures a HikariDataSource, HikariCP initializes a HikariPool instance based on the provided configuration.

The line of code in question typically appears in the initialization logic of HikariDataSource, such as:

1
2
3
4
5

private void initializePool() {
    if (pool == null) {
        pool = fastPathPool = new HikariPool(this);
    }
}

Here, pool and fastPathPool are member variables of HikariDataSource, both pointing to the same HikariPool instance. Let’s break down what this code does.

2. Code Analysis: pool = fastPathPool = new HikariPool(this)

2.1 Key Components

• pool: A member variable in HikariDataSource that stores the HikariPool instance. It serves as the primary entry point for interacting with the connection pool.
• fastPathPool: Another member variable pointing to the same HikariPool instance. The name fastPathPool suggests a potential performance optimization (more on this- new HikariPool(this): Creates a new HikariPool instance, passing the current HikariDataSource (or its configuration object) as a parameter to the HikariPool constructor.
• this: Refers to the HikariDataSource or its related configuration object (e.g., HikariConfig), used to pass configuration details to the pool.

2.2 Why Two Variables?

Assigning the same HikariPool instance to both pool and fastPathPool may seem redundant, but it reflects a design choice for flexibility:

• pool: Acts as the primary reference to the connection pool, used in most scenarios.
• fastPathPool: Indicates a potential performance-optimized path (fast path). While fastPathPool currently points to the same object as pool, this design allows HikariCP to potentially switch to a more optimized pool implementation in specific scenarios without altering the external interface.

This approach provides HikariCP with the flexibility to evolve its internal implementation while maintaining compatibility.

3. HikariPool Constructor Analysis

To understand what new HikariPool(this) does, let’s examine the HikariPool constructor (simplified version):

1
2
3
4
5
6
7
8
9
10
11

public HikariPool(final HikariConfig config) {
    super(config);
    this.connectionTimeout = config.getConnectionTimeout();
    this.validationTimeout = config.getValidationTimeout();
    this.maxLifetime = config.getMaxLifetime();
    this.idleTimeout = config.getIdleTimeout();
    this.leakDetectionThreshold = config.getLeakDetectionThreshold();
    this.poolName = config.getPoolName();
    // Initialize other properties...
    initializeConnections();
}

3.1 Main Tasks of the Constructor

1. Inheritance and Configuration Setup:

   • HikariPool extends PoolBase, which handles foundational operations like creating and closing connections.
   • The constructor takes a HikariConfig object, extracts configuration parameters (e.g., maximum pool size, minimum idle connections, connection timeout), and assigns them to HikariPool member variables.

2. Connection Pool Initialization:

   • Calls initializeConnections() to create the initial set of database connections and populate the pool.
   • Starts background threads (e.g., HouseKeeper) to periodically check connection health, recycle idle connections, and perform other maintenance tasks.

3. Performance Optimization:

   • Uses efficient data structures like ConcurrentBag to manage connections, ensuring high concurrency and low-latency operations for borrowing and returning connections.

3.2 Role of the this Parameter

The this parameter (typically HikariDataSource or HikariConfig) provides the configuration details, such as:

• Database URL, username, and password
• Maximum pool size (maximumPoolSize)
• Minimum idle connections (minimumIdle)
• Connection timeout (connectionTimeout)
• Advanced settings (e.g., connection validation query, leak detection)

HikariPool uses these settings to determine how to initialize and manage connections.

4. Potential Role of fastPathPool

Although fastPathPool currently points to the same object as pool, its naming and design suggest performance optimization possibilities. Here are some speculations and insights:

• Fast Path Optimization: HikariCP might intend to use a specialized pool implementation in certain scenarios, potentially skipping checks (e.g., connection validation) for better performance.
• Dynamic Switching: The existence of fastPathPool allows HikariCP to dynamically switch to a more efficient pool implementation based on runtime conditions or configuration.
• Backward Compatibility: By maintaining both pool and fastPathPool, HikariCP can introduce new pool implementations without breaking existing code.

While fastPathPool’s full potential is not yet utilized, its design leaves room for future enhancements.

5. Conclusion

The line pool = fastPathPool = new HikariPool(this); is a pivotal part of HikariCP’s connection pool initialization. It creates a HikariPool instance and assigns it to both pool and fastPathPool, setting up the core component for managing database connections. The HikariPool constructor handles configuration parsing, pool initialization, and background maintenance tasks.

This code reflects HikariCP’s key strengths:

• High Performance: Efficient data structures and optimized logic ensure low latency and high throughput.
• Flexibility: The fastPathPool design allows for future performance enhancements.
• Simplicity: The initialization logic is clear and maintainable.

By analyzing this code, we gain insight into HikariCP’s connection pool creation process and appreciate its forward-thinking design. For those interested in diving deeper, exploring components like ConcurrentBag or HouseKeeper in the HikariCP source code can reveal even more about its robust implementation.

HikariCP case study 1 Thread Safety

HikariDataSource is a high-performance JDBC connection pooling library widely used in Java applications to manage database connections efficiently. This case study explores a critical aspect of HikariDataSource’s implementation: thread safety, focusing on how it ensures consistent behavior in high-concurrency environments.

Thread Safety in HikariDataSource

A key piece of code in HikariDataSource prevents the use of the connection pool after it has been closed:

1
2
3

if (isClosed()) {
    throw new SQLException("HikariDataSource " + this + " has been closed.");
}

This code checks whether the connection pool is closed. If isClosed() returns true, it throws an exception to prevent further operations. While this appears to be a simple check, it reveals important design considerations for thread safety.

The isClosed() Method

The isClosed() method is implemented as:

1

return isShutdown.get();

Here, isShutdown is a field defined as:

1

private final AtomicBoolean isShutdown = new AtomicBoolean();

The use of AtomicBoolean ensures that the isShutdown state is thread-safe, meaning its value remains consistent across multiple threads, even in high-concurrency scenarios. Java’s Atomic classes, such as AtomicBoolean, AtomicInteger, and AtomicLong, provide atomic operations that guarantee thread safety without explicit synchronization.

This design ensures that when the connection pool is closed, all threads can reliably detect this state, preventing race conditions or inconsistent behavior.

Why Thread Safety Matters

To understand why AtomicBoolean is necessary, we need to explore the root cause of thread safety issues.

Modern CPUs have multiple levels of caching: L1, L2, and L3 caches, which are exclusive to each CPU core, and main memory, which is shared across all cores. When a CPU core performs a computation, it loads data from main memory into its L1 cache for faster access. However, this caching mechanism can lead to inconsistencies across cores.

For example, if one thread updates the isShutdown value on one CPU core, that update may remain in the core’s L1 cache and not immediately propagate to other cores. As a result, other threads running on different cores might read an outdated value of isShutdown, leading to thread-unsafe behavior.

How AtomicBoolean Ensures Thread Safety

AtomicBoolean addresses this issue through the use of a volatile field:

1

private volatile int value;

The value field stores the boolean state (0 for false, 1 for true). The volatile keyword plays a crucial role in ensuring thread safety by enforcing the following:

1. Write Synchronization: When a thread modifies the value, the change is immediately written to main memory, bypassing the CPU cache.
2. Read Synchronization: When a thread reads the value, it always fetches the latest value from main memory, not from the CPU cache.

This ensures that all threads see a consistent value for isShutdown, regardless of which CPU core they are running on.

The Trade-Off of volatile

While volatile guarantees thread safety, it comes with a performance cost. Reading from and writing to main memory is significantly slower than accessing CPU caches. Therefore, using volatile introduces latency, which can impact performance in high-throughput systems.

This trade-off highlights an important lesson: volatile should only be used when thread safety is critical. In cases where a state variable is rarely updated or does not require real-time consistency, a non-volatile field might suffice to avoid the performance overhead.

Lessons from HikariCP’s Source Code

HikariCP’s use of AtomicBoolean demonstrates a careful consideration of thread safety in a high-performance system. However, this is just one example of the library’s low-level optimizations. Other aspects of HikariCP’s design include:

• Bytecode Size Control: HikariCP minimizes bytecode size to improve JVM optimization and reduce overhead.
• Concurrency Patterns: HikariCP employs advanced concurrency techniques, similar to those found in frameworks like Disruptor, which is known for its CPU cache-aware design and exceptional performance.

These optimizations show how understanding low-level details, such as CPU caching and memory synchronization, can lead to more efficient code. For developers, studying frameworks like HikariCP and Disruptor offers valuable insights into writing high-performance applications.

Takeaways

Reading HikariCP’s source code can feel like a deep dive into computer science fundamentals, from CPU caches to JVM optimizations. It serves as a reminder that the abstractions we use in high-level programming are built on intricate low-level mechanisms. As developers, investing time in understanding these details can help us write better, more efficient code.

Reflecting on this, I can’t help but think: All those naps I took in university lectures on operating systems and computer architecture? It’s time to pay them back by diving into the source code!

By learning from frameworks like HikariCP, we can bridge the gap between high-level programming and low-level optimizations, ultimately becoming better engineers.

Algorithm - Dynamic Programming

What is Dynamic Programming?

Principle of Optimality (Bellman, 1957):
An optimal sequence of decisions has the property that whatever the initial state and decision are, the remaining decisions must constitute an optimal decision with regard to the state resulting from the first decision.

The Other Algorithmic Design Philosophy

1. Divide-and-Conquer:
   The problem is divided and the subproblems are processed in a recursive manner, but the solutions of Divide-and-Conquer subproblems are usually not repeated, and when they are repeated, the same subproblems are usually recalculated.

2. Greedy Approach:
   At each stage, starting from a certain starting point, each input is checked one by one to see if it is suitable to be added to the answer. If it is not possible to find a selection procedure to check one by one for the optimization problem to be handled, we will discuss it later.

Divide and Conquer and Dynamic Programming are very similar. The difference is that Dynamic Programming’s subproblems have many overlaps, which can be stored in a table without recalculation, exchanging space for time.

Master Theorem for Exam