Merge pull request #216 from LLNL/release/v0.20

Release/v0.20

CITATION.cff

@@ -0,0 +1,34 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: >-
+  Metall: A Persistent Memory Allocator for
+  Data-Centric Analytics
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Keita
+    family-names: Iwabuchi
+    email: kiwabuchi@llnl.gov
+    affiliation: ' Lawrence Livermore National Laboratory'
+    orcid: 'https://orcid.org/0000-0002-9395-0843'
+  - given-names: 'Roger '
+    family-names: Pearce
+    affiliation: Lawrence Livermore National Laboratory
+  - given-names: Maya
+    family-names: Gokhale
+    affiliation: Lawrence Livermore National Laboratory
+identifiers:
+  - type: url
+    value: 'https://doi.org/10.11578/dc.20190410.1'
+repository-code: 'https://github.com/LLNL/metall'
+abstract: >-
+  Metall is a persistent memory allocator built on
+  top of the memory-mapped file mechanism.
+
+  Metall enables applications to transparently
+  allocate custom C++ data structures into various
+  types of persistent memories.

CMakeLists.txt

@@ -11,7 +11,7 @@ cmake_policy(SET CMP0077 NEW)
 # Metall general configuration
 # -------------------------------------------------------------------------------- #
 project(Metall
-        VERSION 0.19
+        VERSION 0.20
         DESCRIPTION "A persistent memory allocator for data-centric analytics"
         HOMEPAGE_URL "https://github.com/LLNL/metall")
 
@@ -20,6 +20,7 @@ configure_file(MetallConfig.h.in MetallConfig.h)
 # ----- Setting up a INTERFACE library to install header files ----- #
 include(GNUInstallDirs)
 add_library(${PROJECT_NAME} INTERFACE)
+add_library(${PROJECT_NAME}::${PROJECT_NAME} ALIAS ${PROJECT_NAME})
 target_include_directories(${PROJECT_NAME}
         INTERFACE $<BUILD_INTERFACE:${${PROJECT_NAME}_SOURCE_DIR}/include>
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
@@ -56,8 +57,7 @@ write_basic_package_version_file(
 configure_package_config_file(
         "${PROJECT_SOURCE_DIR}/cmake/${PROJECT_NAME}Config.cmake.in"
         "${PROJECT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
-        INSTALL_DESTINATION
-        ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
+        INSTALL_DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
 
 # install config files
 install(FILES

README.md

@@ -44,9 +44,9 @@ For example,
 ```bash
 # Download Boost (Boost C++ Libraries 1.64 or more is required)
 # One can skip this step if Boost is already available.
-wget https://boostorg.jfrog.io/artifactory/main/release/1.77.0/source/boost_1_77_0.tar.gz
-tar xvf boost_1_77_0.tar.gz
-export BOOST_ROOT=$PWD/boost_1_77_0
+wget https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.tar.gz
+tar xvf boost_1_78_0.tar.gz
+export BOOST_ROOT=$PWD/boost_1_78_0
 
 git clone https://github.com/LLNL/metall
 export METALL_INCLUDE=$PWD/metall/include
@@ -115,24 +115,23 @@ doxygen ../docs/Doxyfile.in
 
 # Publication
 
-## Metall: A Persistent Memory Allocator Enabling Graph Processing
-
-* [Paper PDF](https://www.osti.gov/servlets/purl/1576900)
-
-* [IEEE Xplore](https://ieeexplore.ieee.org/document/8945094)
+```
+Keita Iwabuchi, Karim Youssef, Kaushik Velusamy, Maya Gokhale, Roger Pearce,
+Metall: A persistent memory allocator for data-centric analytics,
+Parallel Computing, 2022, 102905, ISSN 0167-8191, https://doi.org/10.1016/j.parco.2022.102905.
+```
 
-## Metall: A Persistent Memory Allocator for Data-Centric Analytics (latest publication, preprint)
+* [Parallel Computing](https://www.sciencedirect.com/science/article/abs/pii/S0167819122000114) (journal)
 
-* [arXiv](https://arxiv.org/abs/2108.07223)
+* [arXiv](https://arxiv.org/abs/2108.07223) (preprint)
 
 # About
 
-## Authors
-
-* Keita Iwabuchi (kiwabuchi at llnl dot gov)
-* Roger A Pearce (rpearce at llnl dot gov)
-* Maya B Gokhale (gokhale2 at llnl dot gov).
+## Contact
 
+- [GitHub Issues](https://github.com/LLNL/metall/issues) is open.
+
+- Primary contact: [Keita Iwabuchi (LLNL)](https://github.com/KIwabuchi).
 
 ## License
 

docs/Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Metall"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v0.19
+PROJECT_NUMBER         = v0.20
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

example/cmake/FetchContent/CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.14)
 include(FetchContent)
 
-project(myproject)
+project(myproject LANGUAGES C CXX)
 
 # Metall requires C++ 17
 set(CMAKE_CXX_STANDARD 17)
@@ -28,11 +28,11 @@ if (NOT BUILD_C)
     set(JUST_INSTALL_METALL_HEADER TRUE)
 endif()
 FetchContent_Declare(
-        metall
+        Metall
         GIT_REPOSITORY https://github.com/LLNL/metall.git
         GIT_TAG master
 )
-FetchContent_MakeAvailable(metall)
+FetchContent_MakeAvailable(Metall)
 
 # ---------------------------------------- #
 #  For using Metall CXX API
@@ -44,22 +44,22 @@ add_executable(cpp_example ../src/cpp_example.cpp)
 # Need Boost header files
 target_include_directories(cpp_example PRIVATE ${Boost_INCLUDE_DIRS})
 
-# Link Metall
-# Although target_link_libraries() is used, no library file (e.g., *.a file) is linked.
-# Only include path will be set here.
-target_link_libraries(cpp_example PRIVATE Metall)
-
 # This is required if one uses GCC.
 target_link_libraries(cpp_example PRIVATE stdc++fs)
 
 target_link_libraries(cpp_example PRIVATE Threads::Threads)
 
+# Link Metall
+# Although target_link_libraries() is used, no library file (e.g., *.a file) is linked.
+# Only include path will be set here.
+target_link_libraries(cpp_example PRIVATE Metall::Metall)
+
 # ---------------------------------------- #
 # For using Metall C API
 # ---------------------------------------- #
 if (BUILD_C)
     add_executable(c_example ../src/c_example.c)
 
     # Link Metall C library (libmetall_c)
-    target_link_libraries(c_example PRIVATE metall_c)
+    target_link_libraries(c_example PRIVATE Metall::metall_c)
 endif ()

example/cmake/find_package/CMakeLists.txt

@@ -1,4 +1,4 @@
-project(myproject)
+project(myproject LANGUAGES C CXX)
 
 # Metall requires C++ 17
 set(CMAKE_CXX_STANDARD 17)

example/json/CMakeLists.txt

@@ -2,4 +2,5 @@ if (Boost_VERSION_STRING VERSION_GREATER_EQUAL "1.75")
     add_metall_executable(json_create json_create.cpp)
     add_metall_executable(json_open json_open.cpp)
     add_metall_executable(jgraph jgraph.cpp)
+    add_metall_executable(vector_of_json vector_of_json.cpp)
 endif()

example/json/vector_of_json.cpp

@@ -0,0 +1,44 @@
+// Copyright 2022 Lawrence Livermore National Security, LLC and other Metall Project Developers.
+// See the top-level COPYRIGHT file for details.
+//
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+#include <iostream>
+#include <metall/metall.hpp>
+#include <metall/container/vector.hpp>
+#include <metall/container/experimental/json/json.hpp>
+
+using namespace metall::container;
+using namespace metall::container::experimental;
+
+int main() {
+  // Metall JSON container works like the other containers w.r.t. allocation, i.e.,
+  // it takes an allocator type in its template parameter and an allocator object in its constructors.
+  using json_value_type = json::value<metall::manager::allocator_type<std::byte>>;
+  // Need to use scoped_allocator as this is a multi-layer container.
+  using vector_json_type = vector<json_value_type, metall::manager::scoped_allocator_type<json_value_type>>;
+
+  // An example input json strings.
+  std::vector<std::string> json_string_list{R"({"name": "Alice", "list": [0, 1]})",
+                                            R"({"name": "Brad", "list": [2, 3]})"};
+
+  // Create a vector-of-json object
+  {
+    metall::manager manager(metall::create_only, "./test");
+    auto *vec = manager.construct<vector_json_type>(metall::unique_instance)(manager.get_allocator());
+    for (const auto &json_string: json_string_list) {
+      vec->emplace_back(json::parse(json_string, manager.get_allocator()));
+    }
+  }
+
+  // Reattach the vector-of-json object created above.
+  {
+    metall::manager manager(metall::open_read_only, "./test");
+    auto *vec = manager.find<vector_json_type>(metall::unique_instance).first;
+    for (const auto &json: *vec) {
+      json::pretty_print(std::cout, json); // Show contents.
+    }
+  }
+
+  return 0;
+}