cachelab started

2025-04-21 23:52:27 +08:00
parent cc99d9b5d9
commit ace7a46fb9
58 changed files with 10071 additions and 0 deletions
--- a/cachelab/cbsl/README.md
+++ b/cachelab/cbsl/README.md
@ -0,0 +1,93 @@
+# CBSL: Compressed Binary Serialization Library
+
+## What's this?
+
+The library provides the binary serialization with the compression by [Zstandard](https://facebook.github.io/zstd/).
+A motivation of the library is to implement the data-compressed checkpoint/restart, which is well-known technique to recover computer failures in high-performance computing.
+This library aims to simple and lightweight access for users.
+
+The library support C99 or later, and Fortran 2008 or later: perhaps we use the features are all supported by major compilers.
+
+## How to build and test
+
+The library uses [CMake](https://cmake.org/) version 3.3.x or later.
+
+    $ cmake --version
+    cmake version 3.14.3
+ 
+    CMake suite maintained and supported by Kitware (kitware.com/cmake).
+    $ mkdir build && cd build
+    $ cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/install/path ..
+    $ make
+    $ make test
+    $ make install
+
+## Do you need help to install `zstd` package?
+
+We can build and install `zstd` automatically in the build process.
+Please pass `-D INSTALL_ZSTD=on` to cmake, we will install `zstd` package where `CMAKE_INSTALL_PREFIX` directory before building the library.
+
+    $ cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/install/path -D INSTALL_ZSTD=on ..
+    $ make
+    $ make test
+    $ make install
+
+## Test environments
+
+1. CMake version 3.14.3
+2. GCC version 4.8.5
+3. Zstandard version 1.4.0
+4. CentOS Linux release 7.5.1804 (Core)
+
+## Benchmark
+
+We provide the library performance benchmark with best and worst case.
+Please be reminded that **the benchmark results not indicate the performance of Zstandard**, these measure the overhead (use cost) of this library.
+
+1. Best case : all data is zero filled (A compression ratio achieves up to 99%)
+2. Worst case : data is generated by rand() (A compression ratio is lower than 1%)
+
+`benchmark` target executes the benchmarks.
+
+    ...
+    $ make benchmark
+    min data size = 262144.00 [B]
+    max data size = 134217728.00 [B]
+    data is zero filled (maximum compression)
+    <write data [Byte]> <time [seconds]> <speed [MiB/sec]>
+    262144    0.002397    109.360615
+    524288    0.002887    181.572393
+    1048576    0.003440    304.827177
+    ...
+
+## Use `zstd` command
+
+A compressed file by the library can be decompressed by `zstd` command.
+
+## License
+
+    Copyright 2019 Yuta Hirokawa (University of Tsukuba, Japan)
+  
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+  
+        http://www.apache.org/licenses/LICENSE-2.0
+  
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+## Future work
+
+1. API error code
+2. Refectoring tests
+
+## NOTE
+
+### Unsupported binary compatibility
+
+The library does not support the binary compatibility and endianness conversion, which is required on the communication across machine.
+If you want it, please consider using other serialization libraries such as [MessagePack](https://msgpack.org/).