Unified Synchronization for GigaMap Storage

[zdenek-jonas]

Description

Currently, GigaMap provides its own internal synchronization when using the GigaMap.store() method. However, when developers use the standard StorageEmbedded.store(gigaMap) entry point, this internal synchronization is not automatically applied.

This requires the developer to manually manage synchronization at the application level specifically for GigaMap instances, even though the component already has the necessary logic built-in. Since StorageEmbedded is the primary API for persisting entities, it is more intuitive for users to expect the same level of thread safety regardless of the storage method used.

Proposed Improvement

To improve User Experience (UX) and API consistency, we should ensure that the standard storage API leverages the internal synchronization of the GigaMap component:

• Automatic Sync Delegation: Update StorageEmbedded.store(Object) to recognize GigaMap instances and utilize their internal synchronization logic.
• Unified API Behavior: Remove the need for manual locking by the programmer when interacting with GigaMap through the global storage manager.

Goal

Simplify the development process by making GigaMap thread-safe by default through all storage entry points, ensuring that the internal synchronization logic is always utilized without additional boilerplate code.

[hrstoyanov]

@fh-ms @zdenek-jonas

Thank you for opening this issue — it directly addresses one of the concerns from #625.

I'd like to share an observation that suggests the fix needs to go deeper than the StorageEmbedded.store(Object) entry point.

The nested GigaMap problem

Consider a GigaMap that contains (directly or via its entity graph) another GigaMap. Even with the proposed fix intercepting at StorageEmbedded.store(), the following scenario remains unsafe:

1. Thread A calls outerGigaMap.store() — acquires the outer GigaMap's monitor ✅
2. Inside store(), the BinaryStorer traverses the outer GigaMap's object graph
3. BinaryStorer.processItems() encounters the inner GigaMap and invokes its type handler (AbstractBinaryHandlerStateChangeFlagged.store())
4. The type handler serializes the inner GigaMap's bitmap index structures — reading EqHashTable.intSize() then iterating entries() — without acquiring the inner GigaMap's monitor ❌
5. Meanwhile, Thread B calls innerGigaMap.add() (which is synchronized on the inner GigaMap), rehashing the EqHashTable between the type handler's size read and iteration
6. Result: BinaryPersistenceException: Inconsistent element count or worse

The application has no way to prevent this. There is no hook to intercept BinaryStorer.processItems(), and the application cannot know which objects the storer will reach during graph traversal.

Why the entry-point fix is insufficient

The proposed improvement — making StorageEmbedded.store(Object) recognize GigaMap instances and delegate to GigaMap.store() — solves the direct case:

storageManager.store(gigaMap); // → would delegate to gigaMap.store() → safe ✅

But it does not help when a GigaMap is reached indirectly during graph traversal:

storageManager.store(parentObject); // parent's graph contains a GigaMap
outerGigaMap.store(); // outer contains inner GigaMap

In both cases, the inner/nested GigaMap is serialized by the type handler, not by GigaMap.store(), so its monitor is never acquired.

Suggested fix: synchronize at the type handler level

GigaMap already acknowledges that mutation and serialization must not overlap — that's why GigaMap.store() is synchronized. The type handler should apply the same guarantee:

// In AbstractBinaryHandlerStateChangeFlagged.store()
@Override
public void store(Binary data, T instance, long objectId, PersistenceStoreHandler handler) {
    synchronized (instance) {
        // existing serialization logic
    }
}

This makes GigaMap safe regardless of how serialization was triggered. The performance impact is minimal: uncontended synchronized on modern JVMs costs a single CAS (~10-20ns), and the contended case (mutation blocked during serialization) matches the existing behavior of gigaMap.store() — the recommended API. If profiling later reveals that lock hold time during serialization of very large GigaMaps is a bottleneck, a snapshot-based approach could decouple serialization from mutation, but synchronized is the correct and simplest first step.