Merge pull request #107 from LLNL/release/2.1.0

Release/2.1.0

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+## [2.1.0]
+### Added 
+- SparseStore: A sparse multi-file backing store interface included [Details](https://llnl-umap.readthedocs.io/en/latest/sparse_store.html)
+- Build Option: -DENABLE_DISPLAY_STATS: option to display statistics before uunmap returns [Details](https://llnl-umap.readthedocs.io/en/latest/advanced_configuration.html)
+- Build Option: -DENABLE_TESTS_LINK_STATIC_UMAP: This allows test binaries to link Umap statically or dynamically [Details](https://llnl-umap.readthedocs.io/en/latest/advanced_configuration.html)
+- Flush Buffer: umap_flush() allows users to explicitly flush dirty pages [#2b36757]
+
+### Fixed
+- Fixed C-compatibility of umap.h [#c489653]
+- Duplicate stats removed [#3b59db9]
+- deadlock in evict_region [#aeb4e6b]
+- Thread-safe umap_ex() and uunmap() API calls ([#13863a6],[#12a740b])
+
+## [2.0.0]
+
+[Unreleased]: https://github.com/LLNL/umap/tree/develop
+[2.1.0]: https://github.com/LLNL/umap/tree/release-test
+[2.0.0]: https://github.com/LLNL/umap/tree/release-2.0.0
+[#13863a6]: https://github.com/LLNL/umap/commit/13863a60121072660bb459d03f1a185b082a37c8
+[#aeb4e6b]: https://github.com/LLNL/umap/commit/86fd5937aeb4e6bb73dd689a6975cb225a4b3725
+[#12a740b]: https://github.com/LLNL/umap/commit/12a740bd85ddd57d50a00071644d4d654176375c
+[#c489653]: https://github.com/LLNL/umap/commit/c4896535eacd9266a0c00744f9c14c389a3c89a0
+[#3b59db9]: https://github.com/LLNL/umap/commit/3b59db93d29bca092e702ea93f9712e8cc5f147f
+[#2b36757]: https://github.com/LLNL/umap/commit/2b36757ae5f83836dafc63702b12bda480f17540
+

CMakeLists.txt

@@ -1,30 +1,37 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only
 #############################################################################
 cmake_minimum_required (VERSION 3.5.1)
 project(umap
-  VERSION 2.0.0
+  VERSION 2.1.0
   LANGUAGES CXX C
 )
 
 OPTION (ENABLE_TESTS "Selects whether tests are built." On)
 OPTION (ENABLE_LOGGING "Build umap with Logging enabled" On)
+OPTION (ENABLE_DISPLAY_STATS "Display umap statistics when closing" Off)
+OPTION (ENABLE_TESTS_LINK_STATIC_UMAP "Build tests statically linked to umap" Off)
 
 include(cmake/BuildEnv.cmake)
 include(cmake/BuildType.cmake)
 include(cmake/SetupUmapThirdParty.cmake)
 
 set(UMAP_DEBUG_LOGGING ${ENABLE_LOGGING})
+set(UMAP_DISPLAY_STATS ${ENABLE_DISPLAY_STATS})
 configure_file(
   ${PROJECT_SOURCE_DIR}/config/config.h.in
   ${PROJECT_BINARY_DIR}/src/umap/config.h)
 
 include_directories ( "${CMAKE_SOURCE_DIR}/src" "${CMAKE_BINARY_DIR}/src")
 
 add_subdirectory(src)
-add_subdirectory(examples)
-add_subdirectory(tests)
+
+if (ENABLE_TESTS)
+  set(STATIC_UMAP_LINK ${ENABLE_TESTS_LINK_STATIC_UMAP} CACHE BOOL "Linking option for Umap binaries" FORCE)
+  add_subdirectory(examples)
+  add_subdirectory(tests)
+endif()
 

README.md

@@ -1,4 +1,4 @@
-# UMAP v2.0.0
+# UMAP v2.1.0
 
 [![Travis Build Status](https://travis-ci.com/LLNL/umap.svg?branch=develop)](https://travis-ci.com/LLNL/umap)
 [![Documentation Status](https://readthedocs.org/projects/llnl-umap/badge/?version=develop)](https://llnl-umap.readthedocs.io/en/develop/?badge=develop)
@@ -21,7 +21,7 @@ including a hello world program for userfaultfd based upon code from the
 ```bash
 mkdir build
 cd build
-cmake -DCMAKE_INSTALL_PREFIX = <where you want the sofware> ..
+cmake -DCMAKE_INSTALL_PREFIX=<where you want the sofware> ..
 make install
 ```
 
@@ -33,6 +33,10 @@ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-dir> ..
 
 ## Documentation
 
+The design and implementation of UMap is described in the following paper:
+
+```Peng, Ivy B., Marty McFadden, Eric Green, Keita Iwabuchi, Kai Wu, Dong Li, Roger Pearce, and Maya Gokhale. "UMap: Enabling Application-driven Optimizations for Page Management". In Proceedings of the Workshop on Memory Centric High Performance Computing. ACM, 2018.```
+
 Both user and code documentation is available
 [here](http://llnl-umap.readthedocs.io/).
 
@@ -44,8 +48,11 @@ If you have build problems, we have comprehensive
 - The license is [LGPL](/LICENSE).
 - [thirdparty_licenses.md](/thirdparty_licenses.md)
 
+`LLNL-CODE-733797`
+
 ## Contact
 
 - Marty McFadden  ([email protected])
 - Maya Gokhale ([email protected])
 - Eric Green ([email protected])
+- Abhik Sarkar ([email protected])

RELEASE

@@ -0,0 +1,17 @@
+Umap Version 2.1
+
+Copyright (c) 2016-20, Lawrence Livermore National Security, LLC. and other
+UMAP Project Developers.  Produced at the Lawrence Livermore National
+Laboratory.  All rights reserved. See details in umap/LICENSE.
+
+Open Source – LGPL-2.1-only
+LLNL-CODE-733797
+
+Created by Abhik Sarkar ([email protected])
+
+Contributors:
+- Marty McFadden ([email protected])
+- Eric Green ([email protected])
+- Ivy Peng ([email protected])
+- Maya Gokhale ([email protected])
+- Abhik Sarkar ([email protected])

cmake/BuildType.cmake

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only

cmake/SetupUmapThirdParty.cmake

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only

config/config.h.in

@@ -1,5 +1,5 @@
 //////////////////////////////////////////////////////////////////////////////
-// Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+// Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 // UMAP Project Developers. See the top-level LICENSE file for details.
 //
 // SPDX-License-Identifier: LGPL-2.1-only
@@ -11,4 +11,5 @@
 #define UMAP_VERSION_MINOR @umap_VERSION_MINOR@
 #define UMAP_VERSION_PATCH @umap_VERSION_PATCH@
 #cmakedefine UMAP_DEBUG_LOGGING
+#cmakedefine UMAP_DISPLAY_STATS
 #endif

docs/doxygen/Doxyfile

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only

docs/sphinx/advanced_configuration.rst

@@ -18,7 +18,9 @@ Here is a summary of the configuration options, their default value, and meaning
       Variable                     Default  Meaning
       ===========================  ======== ==========================================
       ``ENABLE_LOGGING``           On       Enable Logging within umap
+      ``ENABLE_DISPLAY_STATS``     Off      Enable Displaying umap stats at close
       ``ENABLE_TESTS``             On       Enable building and installation of tests
+      ``ENABLE_TESTS_LINK_STATIC_UMAP``  Off      Generate tests statically linked with Umap
       ``CMAKE_CXX_COMPILER``       not set  Specify C++ compiler to use
       ``DCMAKE_CC_COMPILER``       not set  Specify C compiler to use
       ===========================  ======== ==========================================
@@ -27,11 +29,18 @@ These arguments are explained in more detail below:
 
 * ``ENABLE_LOGGING``
   This option enables usage of Logging services for umap.  When this support is
-  enabled, you may cause umap library to emit log files by setting the ``UMAP_LOGGING``
-  environment variable to "1" (for information-only logs), "2" (for more verbose
-  logs), and "3" for all debug messages to be emitted to a log file.
+  enabled, you may cause umap library to emit log files by setting the ``UMAP_LOG_LEVEL``
+  environment variable to "INFO" (for information-only logs), "WARNING" (for warning info
+  logs), "ERROR" for (for errors only logs), and "DEBUG" for all debug messages to be emitted to a log file.
+
+* ``ENABLE_DISPLAY_STATS``
+  When this option is turned on, the umap library will display its runtime
+  statistics before unmap() completes.
 
 * ``ENABLE_TESTS``
   This option enables the compilation of the programs under the tests directory
   of the umap source code.
 
+* ``ENABLE_TESTS_LINK_STATIC_UMAP``
+  This option enables the compilation of the programs under the tests directory
+  of the umap source code against static umap library.

docs/sphinx/conf.py

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only

docs/sphinx/environment_variables.rst

@@ -0,0 +1,57 @@
+.. _environment_variables:
+
+=============================
+Runtime Environment Variables
+=============================
+
+The interface to the umap runtime library configuration is controlled by
+the following environment variables.
+
+.. code-block:: bash
+
+    UMAP_PAGESIZE=$((2*4096)) your_program_that_uses_umap
+
+The following environment varialbles may be set:
+
+* ``UMAP_PAGE_FILLERS``
+  This is the number of worker threads that will perform read operations from
+  the backing store (including read-ahead) for a specific umap region.
+
+  Default: `std::thread::hardware_concurrency()`
+
+* ``UMAP_PAGE_EVICTORS``
+  This is the number of worker threads that will perform evictions of pages.
+  Eviction includes writing to the backing store if the page is dirty and
+  telling the operating system that the page is no longer needed.
+
+  Default: `std::thread::hardware_concurrency()`
+
+* ``UMAP_EVICT_HIGH_WATER_THRESHOLD``
+  This is an integer percentage of present pages in the Umap Buffer that
+  informs the Eviction workers that it is time to start evicting pages.
+
+  Default: 90
+
+* ``UMAP_EVICT_LOW_WATER_THRESHOLD``
+  This is an integer percentage of present pages in the Umap Buffer that
+  informs the Eviction workers when to stop evicting.
+
+  Default: 70
+
+* ``UMAP_PAGESIZE``
+  This is the size of the umap pages.  This must be a multiple of the system
+  page size.
+
+  Default: System Page Size
+
+* ``UMAP_BUFSIZE``
+  This is the total number of umap pages that may be present within the Umap
+  Buffer.
+
+  Default: (90% of free memory)
+
+* ``UMAP_READ_AHEAD``
+  This is the number of umap pages that Umap will read-ahead on whenever the
+  Buffer is less than the ``UMAP_EVICT_LOW_WATER_THRESHOLD`` amount.
+
+  Default: 0

docs/sphinx/getting_started.rst

@@ -38,7 +38,7 @@ Basic Usage
 The interface to umap mirrors that of mmap(2) as shown:
 
 .. literalinclude:: ../../examples/psort.cpp
-                    :lines: 29-33
+                    :lines: 57-64
 
 The following code is a simple example of how one may use umap:
 

docs/sphinx/index.rst

@@ -1,5 +1,5 @@
 ***********
-UMAP v2.0.0
+UMAP v2.1.0
 ***********
 
 Umap is a library that provides an mmap()-like interface to a simple, user-
@@ -28,6 +28,8 @@ Any questions? File an issue on GitHub.
   :caption: Reference
 
   advanced_configuration
+  environment_variables
+  sparse_store
 
 .. toctree::
   :maxdepth: 2

docs/sphinx/requirements.txt

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright 2017-2019 Lawrence Livermore National Security, LLC and other
+# Copyright 2017-2020 Lawrence Livermore National Security, LLC and other
 # UMAP Project Developers. See the top-level LICENSE file for details.
 #
 # SPDX-License-Identifier: LGPL-2.1-only

docs/sphinx/sparse_store.rst

@@ -0,0 +1,88 @@
+.. _sparse_store
+
+==========================================
+Sparse Multi-files Backing Store Interface
+==========================================
+
+UMap provides an extensible design that supports multiple types of backing stores (e.g., local SSDs, network-interconnected SSDs, and HDDs). 
+
+An application that uses UMap can extend the abstract "Store" class to implement its specific backing store interface.
+
+The default store object used by UMap is "StoreFile", which reads and writes to a single regular Linux file.
+
+UMap also provides a sparse multi-files store object called "SparseStore", which creates multiple backing files dynamically and only when needed. 
+
+Below is an example of using UMap with a SparseStore object.
+
+.. code-block:: c
+
+    #include <umap/umap.h>
+    #include <umap/store/SparseStore.h>
+    #include <string>
+    #include <iostream>
+
+    void use_sparse_store(
+      std::string root_path,
+      uint64_t numbytes,
+      void* start_addr,
+      size_t page_size,
+      size_t file_size){
+
+     void * region = NULL;
+     
+     // Instantiating a SparseStore objct, the "file_size" parameter specifies the granularity of each file. 
+     // An application that desires to create N files can calculate the file size using totalbytes / num_files
+     // Note that the file size is rounded to be a multiple of the page size, 
+     // which results in a number of files that close but not exactly equal to N
+     Umap::SparseStore* sparse_store;
+     sparse_store = new Umap::SparseStore(numbytes,page_size,root_path,file_size);
+
+     // Check status to make sure that the store object was able to open the directory
+     if (store->get_directory_creation_status() != 0){
+       std::cerr << "Error: Failed to create directory at " << root_path << std::endl;
+       return NULL;
+     }
+
+     // set umap flags
+     int flags = UMAP_PRIVATE;
+     
+     if (start_addr != nullptr)
+      flags |= MAP_FIXED;
+
+     const int prot = PROT_READ|PROT_WRITE;
+
+     /* Map region using UMap, Here, the file descriptor passed to umap is -1, as we do not start with mapping a file
+        instead, file(s) will be created incrementally as needed using the "sparse_store" object. */
+
+     region = umap_ex(start_addr, numbytes, prot, flags, -1, 0, sparse_store);
+     if ( region == UMAP_FAILED ) {
+       std::ostringstream ss;
+       ss << "umap_mf of " << numbytes
+          << " bytes failed for " << root_path << ": ";
+       perror(ss.str().c_str());
+       exit(-1);
+     }
+
+     /*
+      * some code that uses mapped region goes here. 
+      */
+
+    // Unmap region
+    if (uunmap(region, numbytes) < 0) {
+      std::ostringstream ss;
+      ss << "uunmap of failure: ";
+      perror(ss.str().c_str());
+      exit(-1);
+    }
+    // NOTE: the method "close_files" from SparseStore MUST be called explicitely before deleting the object
+    int sparse_store_close_files = store->close_files();
+    if (sparse_store_close_files != 0 ){
+      std::cerr << "Error closing SparseStore files" << std::endl;
+      delete store;
+      exit(-1);
+    }
+    delete store; 
+   } 
+
+
+