fixed https://github.com/OpenHFT/Chronicle-Map/issues/211

src/main/java/net/openhft/chronicle/map/ChronicleMap.java

@@ -213,5 +213,36 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>,
      * @return the value Class or UnresolvedType if unknown.
      */
     Type valueType();
-}
 
+    /**
+     * @return the amount of free space in the map as  a percentage.
+     * When the free space gets low ( around 5% ) the map will automatically expand. The
+     * number of times it can automatically expand is based on the
+     * {@code net.openhft.chronicle.map.ChronicleMapBuilder#maxBloatFactor}. If the map
+     * expands you will see an increase in the available free space. It is not possible to
+     * expand the chronicle map manually.
+     *
+     * see also {@see net.openhft.chronicle.map.ChronicleMap#remainingAutoResizes} as these operations are related.
+     */
+    default short percentageFreeSpace() {
+        throw new UnsupportedOperationException("todo");
+    }
+
+    /**
+     * @return the number of times in the future the map can expand its capacity
+     * ( by expending capacity we mean the number of possible entries that
+     * Can be stored into the map), the map will expand automatically, however, there is an upper limit to the
+     * number of times the map can expand.
+     * This limit is set via the {@code net.openhft.chronicle.map.ChronicleMapBuilder#maxBloatFactor} if
+     * the {@code remainingResizes} drops to zero,
+     * then the map is no longer able to resize, if subsequently, the free space
+     * ( see  {@link net.openhft.chronicle.map.ChronicleMap#percentageFreeSpace}) if the map becomes low ( around 5% ),
+     * the map will not be able to take more entries and will fail with an {@code
+     * java.lang.IllegalStateException} for production systems it is recommended you periodically monitor this result and the both the
+     * {@link net.openhft.chronicle.map.ChronicleMap#percentageFreeSpace}.
+     */
+    default int remainingAutoResizes() {
+        throw new UnsupportedOperationException("todo");
+    }
+
+}

src/main/java/net/openhft/chronicle/map/ChronicleMapBuilder.java

@@ -204,7 +204,7 @@ public final class ChronicleMapBuilder<K, V> implements
     private int maxChunksPerEntry = -1;
     private int alignment = UNDEFINED_ALIGNMENT_CONFIG;
     private long entries = -1L;
-    private double maxBloatFactor = 1.0;
+    double maxBloatFactor = 1.0;
     private boolean allowSegmentTiering = true;
     private double nonTieredSegmentsPercentile = 0.99999;
     private boolean aligned64BitMemoryOperationsAtomic = OS.is64Bit();

src/main/java/net/openhft/chronicle/map/VanillaChronicleMap.java

@@ -16,6 +16,9 @@
 
 package net.openhft.chronicle.map;
 
+import impl.CompiledMapIterationContext;
+import impl.CompiledMapQueryContext;
+import net.openhft.chronicle.algo.bitset.ReusableBitSet;
 import net.openhft.chronicle.algo.hashing.LongHashFunction;
 import net.openhft.chronicle.bytes.Bytes;
 import net.openhft.chronicle.bytes.BytesStore;
@@ -34,7 +37,9 @@ import net.openhft.chronicle.hash.serialization.DataAccess;
 import net.openhft.chronicle.hash.serialization.SizeMarshaller;
 import net.openhft.chronicle.hash.serialization.SizedReader;
 import net.openhft.chronicle.hash.serialization.impl.SerializationBuilder;
-import net.openhft.chronicle.map.impl.*;
+import net.openhft.chronicle.map.impl.IterationContext;
+import net.openhft.chronicle.map.impl.NullReturnValue;
+import net.openhft.chronicle.map.impl.QueryContextInterface;
 import net.openhft.chronicle.map.impl.ret.InstanceReturnValue;
 import net.openhft.chronicle.set.ChronicleSet;
 import net.openhft.chronicle.wire.WireIn;
@@ -51,11 +56,14 @@ import java.util.function.Function;
 
 import static net.openhft.chronicle.map.ChronicleMapBuilder.greatestCommonDivisor;
 
+@SuppressWarnings("JavadocReference")
 public class VanillaChronicleMap<K, V, R>
         extends VanillaChronicleHash<K, MapEntry<K, V>, MapSegmentContext<K, V, ?>,
         ExternalMapQueryContext<K, V, ?>>
         implements AbstractChronicleMap<K, V> {
 
+    private final double maxBloatFactor;
+
     public SizeMarshaller valueSizeMarshaller;
     public SizedReader<V> valueReader;
     public DataAccess<V> valueDataAccess;
@@ -98,6 +106,7 @@ public class VanillaChronicleMap<K, V, R>
         valueSizeMarshaller = valueBuilder.sizeMarshaller();
         valueReader = valueBuilder.reader();
         valueDataAccess = valueBuilder.dataAccess();
+        maxBloatFactor = builder.maxBloatFactor;
 
         constantlySizedEntry = builder.constantlySizedEntries();
 
@@ -226,6 +235,51 @@ public class VanillaChronicleMap<K, V, R>
         return valueClass;
     }
 
+    private long tiersUsed() {
+        return globalMutableState().getExtraTiersInUse();
+    }
+
+    private long maxTiers() {
+        return (long) (maxBloatFactor * actualSegments);
+    }
+
+    @Override
+    public int remainingAutoResizes() {
+        return (int) (maxTiers() - tiersUsed());
+    }
+
+    @Override
+    public short percentageFreeSpace() {
+
+        double totalUsed = 0;
+        double totalSize = 0;
+
+        try (IterationContext<K, V, ?> c = iterationContext()) {
+            for (int segmentIndex = 0; segmentIndex < segments(); segmentIndex++) {
+                c.initSegmentIndex(segmentIndex);
+
+                if (!(c instanceof CompiledMapIterationContext))
+                    continue;
+                CompiledMapIterationContext c1 = (CompiledMapIterationContext) c;
+
+                c1.goToFirstTier();
+                ReusableBitSet freeList = c1.freeList();
+                totalUsed += freeList.cardinality();
+                totalSize += freeList.logicalSize();
+
+                while (c1.hasNextTier()) {
+                    c1.nextTier();
+                    ReusableBitSet freeList0 = c1.freeList();
+                    totalUsed += freeList0.cardinality();
+                    totalSize += freeList.logicalSize();
+                }
+
+            }
+        }
+
+        return (short) (100 - (int) (100 * totalUsed / totalSize));
+    }
+
     @NotNull
     @Override
     public final Closeable acquireContext(K key, V usingValue) {