Merge pull request #435 from qubic/develop (Release v1.247.0)

Release v1.247.0

Author: Franziska-Mueller

doc/contracts.md

@@ -470,6 +470,23 @@ The callbacks `PRE_RELEASE_SHARES()` and `PRE_ACQUIRE_SHARES()` may also check t
 
 ## Other QPI features
 
+### Container types
+
+The following container types are available in the QPI:
+
+- `Array<T, L>`: Array of L elements of type T (L must be 2^N)
+- `BitArray<L>`: Array of L bits encoded in array of uint64 (L must be 2^N, overall size is at least 8 bytes)
+- `Collection<T, L>`: Collection of priority queues of elements with type T and total element capacity L. Each ID pov (point of view) has an own queue.
+- `HashMap<KeyT, ValueT, L>`: Hash map of up to L pairs of key and value (types KeyT and ValueT). Lookup by key, insert, and remove run in approximately constant time if population is less than 80% of L.
+- `HashSet`: Hash set of keys of type KeyT and total element capacity L. Lookup by key, insert, and remove run in approximately constant time if population is less than 80% of L.
+
+Please note that removing items from `Collection`, `HashMap`, and `HashSet` does not immediately free the hash map slots used for the removed items.
+This may negatively impact the lookup speed, which depends on the maximum population seen since the last cleanup.
+If the container isn't emptied by calling the method `reset()` regularly (such as at the end of each epoch), it is recommended to call `cleanup()` or `cleanupIfNeeded()` at the end of the epoch.
+Alternatively, if you expect a lot of removes during an epoch, you may call `cleanupIfNeeded()` at the end of a user procedure that removes items.
+Cleanup isn't done automatically when removing elements, because, first, it is very expensive compared to the lookup, the add, and remove operations and second, because it invalidates the indices of items, which may be used by the calling function.
+
+
 ### Calling other user functions and  procedures
 
 TODO: invoking procedures, calling functions, including those of other contracts

src/contract_core/contract_def.h

@@ -239,6 +239,7 @@ constexpr unsigned short TESTEXD_CONTRACT_INDEX = (CONTRACT_INDEX + 1);
 // inaccessible for contracts
 #include "qpi_collection_impl.h"
 #include "qpi_trivial_impl.h"
+#include "qpi_hash_map_impl.h"
 
 #include "platform/global_var.h"
 

src/contract_core/qpi_collection_impl.h

@@ -554,13 +554,23 @@ namespace QPI
 						}
 						break;
 					}
+					// TODO: reuse slots marked for removal, as in HashSet
 					povIndex = (povIndex + 1) & (L - 1);
 				}
 			}
 		}
 		return NULL_INDEX;
 	}
 
+	template <typename T, uint64 L>
+	void Collection<T, L>::cleanupIfNeeded(uint64 removalThresholdPercent)
+	{
+		if (_markRemovalCounter > (removalThresholdPercent * L / 100))
+		{
+			cleanup();
+		}
+	}
+
 	template <typename T, uint64 L>
 	void Collection<T, L>::cleanup()
 	{