Update documents regarding macros

docs/readthedocs/basics/compile_time_options.md

@@ -1,36 +1,4 @@
 # Compile-Time Options
 
-There are some compile-time options (C/C++ macro) as follows to configure the behavior of Metall:
-
-- METALL_DEFAULT_CAPACITY=*bytes*
-  - The default capacity of a segment/datastore.
-  - This value is used when a user does not specify the capacity of a datastore when creating it.
-
-- METALL_VERBOSE_SYSTEM_SUPPORT_WARNING
-  - If defined, Metall shows warning messages at compile time if the system does not support important features.
-
-- METALL_DISABLE_CONCURRENCY
-  - Disable concurrency support in Metall. This option is useful when Metall is used in a single-threaded application.
-  - If this macro is defined, applications must not call Metall concurrently from multiple threads.
-  - Even if this option is enabled, Metall still uses multiple threads for background tasks, such as synchronizing segment files.
-
-- METALL_USE_SORTED_BIN
-  - If defined, Metall stores addresses in sorted order in the bin directory.
-  - This option enables Metall to use memory space more efficiently, but it increases the cost of the bin directory operations.
-
-- METALL_FREE_SMALL_OBJECT_SIZE_HINT=*bytes*
-  - If defined, Metall tries to free space when an object equal to or larger than the specified bytes is deallocated.
-  - Will be rounded up to a multiple of the page size internally.
-
-
-**Macros for the segment storage manager:**
-
-- METALL_SEGMENT_BLOCK_SIZE=*bytes*
-  - The segment block size.
-  - Metall allocates a backing file with this size.
-
-- METALL_DISABLE_FREE_FILE_SPACE
-  - If defined, Metall does not free file space.
-
-- METALL_USE_ANONYMOUS_NEW_MAP
-  - If defined, Metall uses anonymous memory mapping instead of file mapping when creating a new map region.
+There are some compile-time options (C/C++ macro) to configure the behavior of Metall.
+Those macros are defined in `metall/include/metall/defs.hpp`.

include/metall/defs.hpp

@@ -12,14 +12,10 @@
 /// \def METALL_MAX_CAPACITY
 /// The max capacity, i.e., the maximum total memory size a single Metall
 /// datastore can allocate. This value is a theoretical limit, and the actual
-/// limit is smaller than this value.
+/// limit is smaller than this value. This value is used to determine the types
+/// of some internal variables.
 #ifndef METALL_MAX_CAPACITY
-#define METALL_MAX_CAPACITY (1ULL << 48ULL)
-#endif
-
-#ifdef METALL_MAX_SEGMENT_SIZE
-#warning \
-    "METALL_MAX_SEGMENT_SIZE is deprecated. Use METALL_MAX_CAPACITY instead."
+#define METALL_MAX_CAPACITY (1ULL << 47ULL)
 #endif
 
 /// \def METALL_DEFAULT_CAPACITY
@@ -36,20 +32,52 @@
 #endif
 #endif
 
-#ifdef METALL_DEFAULT_VM_RESERVE_SIZE
-#warning \
-    "METALL_DEFAULT_VM_RESERVE_SIZE is deprecated. Use METALL_DEFAULT_CAPACITY instead."
+#ifdef DOXYGEN_SKIP
+/// \brief If defined, Metall shows warning messages at compile time if the
+/// system does not support important features.
+#define METALL_VERBOSE_SYSTEM_SUPPORT_WARNING
+
+/// \brief If defined, Metall stores addresses in sorted order in the bin
+/// directory. This option enables Metall to use memory space more efficiently,
+/// but it increases the cost of the bin directory operations.
+#define METALL_USE_SORTED_BIN
+
+/// \brief If defined, Metall tries to free space when an object equal to or
+/// larger than the specified bytes is deallocated. Will be rounded up to a
+/// multiple of the page size internally.
+#define METALL_FREE_SMALL_OBJECT_SIZE_HINT
 #endif
 
+// --------------------
+// Macros for the default segment storage manager
+// --------------------
+
 /// \def METALL_SEGMENT_BLOCK_SIZE
 /// The segment block size the default segment storage use.
 #ifndef METALL_SEGMENT_BLOCK_SIZE
 #define METALL_SEGMENT_BLOCK_SIZE (1ULL << 28ULL)
 #endif
 
-#ifdef METALL_INITIAL_SEGMENT_SIZE
-#warning \
-    "METALL_INITIAL_SEGMENT_SIZE is deprecated. Use METALL_SEGMENT_BLOCK_SIZE instead."
+#ifdef DOXYGEN_SKIP
+/// \brief If defined, the default segment storage does not free file space even
+/// thought the corresponding segment becomes free.
+#define METALL_DISABLE_FREE_FILE_SPACE
+#endif
+
+// --------------------
+// Macros for the object cache
+// --------------------
+
+/// \def METALL_MAX_PER_CPU_CACHE_SIZE
+/// The maximum size of the per CPU (logical CPU core) cache in bytes.
+#ifndef METALL_MAX_PER_CPU_CACHE_SIZE
+#define METALL_MAX_PER_CPU_CACHE_SIZE (1ULL << 20ULL)
+#endif
+
+/// \def METALL_NUM_CACHES_PER_CPU
+/// The number of caches per CPU (logical CPU core).
+#ifndef METALL_NUM_CACHES_PER_CPU
+#define METALL_NUM_CACHES_PER_CPU 2
 #endif
 
 #ifdef DOXYGEN_SKIP
@@ -63,16 +91,22 @@
 #define METALL_DISABLE_CONCURRENCY
 #endif
 
-/// \def METALL_MAX_PER_CPU_CACHE_SIZE
-/// The maximum size of the per CPU (logical CPU core) cache in bytes.
-#ifndef METALL_MAX_PER_CPU_CACHE_SIZE
-#define METALL_MAX_PER_CPU_CACHE_SIZE (1ULL << 20ULL)
+// --------------------
+// Deprecated macros
+
+#ifdef METALL_MAX_SEGMENT_SIZE
+#warning \
+    "METALL_MAX_SEGMENT_SIZE is deprecated. Use METALL_MAX_CAPACITY instead."
 #endif
 
-/// \def METALL_NUM_CACHES_PER_CPU
-/// The number of caches per CPU (logical CPU core).
-#ifndef METALL_NUM_CACHES_PER_CPU
-#define METALL_NUM_CACHES_PER_CPU 2
+#ifdef METALL_DEFAULT_VM_RESERVE_SIZE
+#warning \
+    "METALL_DEFAULT_VM_RESERVE_SIZE is deprecated. Use METALL_DEFAULT_CAPACITY instead."
+#endif
+
+#ifdef METALL_INITIAL_SEGMENT_SIZE
+#warning \
+    "METALL_INITIAL_SEGMENT_SIZE is deprecated. Use METALL_SEGMENT_BLOCK_SIZE instead."
 #endif
 
 #endif  // METALL_DEFS_HPP