444 lines
12 KiB
Markdown
444 lines
12 KiB
Markdown
# CBSL library references
|
|
|
|
# Build and link libraries
|
|
|
|
## C
|
|
|
|
```bash
|
|
export CBSL_INCLUDE_PATH=${CBSL_INSTALLED_PATH}/include
|
|
export CBSL_LIBRARY_PATH=${CBSL_INSTALLED_PATH}/lib
|
|
|
|
cc -c xcbsl_use_code.c -I${CBSL_INCLUDE_PATH}
|
|
cc -o xcbsl_use_program ${OBJS} -lcbsl -lzstd -L${CBSL_LIBRARY_PATH}
|
|
```
|
|
|
|
## Fortran
|
|
|
|
```bash
|
|
export CBSL_INCLUDE_PATH=${CBSL_INSTALLED_PATH}/include
|
|
export CBSL_LIBRARY_PATH=${CBSL_INSTALLED_PATH}/lib
|
|
|
|
f95 -c xcbslf_use_code.f95 -I${CBSL_INCLUDE_PATH}
|
|
f95 -o xcbslf_use_program ${OBJS} -lcbslf -lcbsl -lzstd -L${CBSL_LIBRARY_PATH}
|
|
```
|
|
|
|
# API
|
|
|
|
We provide `cbslf` module for using the library in Fortran application.
|
|
|
|
## Versioning
|
|
|
|
|Version|Value |
|
|
|-------|-----------------------|
|
|
|major |release year (ex. 2019)|
|
|
|minor |release month (ex. 5) |
|
|
|patch |patch version (0-9) |
|
|
|
|
### C
|
|
|
|
```c
|
|
#define CBSL_VERSION // full version (integer)
|
|
#define CBSL_VERSION_STRING // full version (string)
|
|
#define CBSL_MAJOR_VERSION // major
|
|
#define CBSL_MINOR_VERSION // minor
|
|
#define CBSL_PATCH_VERSION // patch
|
|
```
|
|
|
|
### Fortran
|
|
|
|
```fortran
|
|
integer(8), parameter :: CBSL_VERSION
|
|
character(*), parameter :: CBSL_VERSION_STRING
|
|
integer(4), parameter :: CBSL_MAJOR_VERSION
|
|
integer(4), parameter :: CBSL_MINOR_VERSION
|
|
integer(4), parameter :: CBSL_PATCH_VERSION
|
|
```
|
|
|
|
## Types
|
|
|
|
### C
|
|
|
|
```c
|
|
// library context
|
|
typedef struct cbsl_ctx_ cbsl_ctx;
|
|
```
|
|
### Fortran
|
|
|
|
```fortran
|
|
type(cbslf_context)
|
|
```
|
|
|
|
## Constant values
|
|
|
|
### C
|
|
|
|
```c
|
|
// Context mode
|
|
typedef enum
|
|
{
|
|
cbsl_load_mode, // deserialize mode
|
|
cbsl_store_mode, // serialize mode
|
|
cbsl_unknown_mode // unknown
|
|
}
|
|
cbsl_mode;
|
|
|
|
// Errors
|
|
typedef enum
|
|
{
|
|
cbsl_success, // no error
|
|
cbsl_error // function happens any error
|
|
}
|
|
cbsl_errors;
|
|
```
|
|
|
|
### Fortran
|
|
|
|
```fortran
|
|
integer(4), parameter :: cbslf_load_mode
|
|
integer(4), parameter :: cbslf_store_mode
|
|
integer(4), parameter :: cbslf_unknown_mode
|
|
|
|
integer(4), parameter :: cbslf_success
|
|
integer(4), parameter :: cbslf_errors
|
|
```
|
|
|
|
## API
|
|
|
|
### C
|
|
|
|
```c
|
|
/*
|
|
[brief]
|
|
open serialized data file stream.
|
|
[arguments]
|
|
open_mode: specifies load/store mode
|
|
path : data file path
|
|
[return]
|
|
success : return context pointer
|
|
fail : NULL pointer
|
|
*/
|
|
cbsl_ctx* cbsl_open(cbsl_mode open_mode, char* path);
|
|
|
|
/*
|
|
[brief]
|
|
close serialized data file stream.
|
|
this function calls cbsl_flush() before closing stream.
|
|
[arguments]
|
|
ctx : context pointer
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_close(cbsl_ctx* ctx);
|
|
|
|
/*
|
|
[brief]
|
|
flush file stream.
|
|
this function executes data compression and write to file stream.
|
|
[arguments]
|
|
ctx : context pointer
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_flush(cbsl_ctx* ctx);
|
|
|
|
/*
|
|
[brief]
|
|
the data stores with compression.
|
|
this function stores internal buffer to stored data.
|
|
When the stored data fills enough size to compress, this function calls cbsl_flush().
|
|
[arguments]
|
|
ctx : context pointer
|
|
data : write data pointer (must be allocated)
|
|
size : byte size of data
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_write(cbsl_ctx* ctx, const void* data, uint64_t size);
|
|
|
|
/*
|
|
[brief]
|
|
the data loads with decompression.
|
|
this function decompresses data from a file stream, and loads from internal decompressed buffer.
|
|
[arguments]
|
|
ctx : context pointer
|
|
data : read data pointer (must be allocated)
|
|
size : byte size of data
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_read(cbsl_ctx* ctx, void* data, uint64_t size);
|
|
|
|
/*
|
|
[brief]
|
|
the data loads/stores with compression/decompression.
|
|
this function calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
|
|
[argumetns]
|
|
ctx : context pointer
|
|
data : read/write data pointer (must be allocated)
|
|
size : byte size of data
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_record(cbsl_ctx* ctx, void* data, uint64_t size);
|
|
|
|
/*
|
|
[brief]
|
|
this is a specialized function of cbsl_record() for heap allocated array.
|
|
the function loads/stores array data size [bytes] and array values from/to a file stream.
|
|
an array will be allocated on heap memory by malloc() routine if `data` is null pointer.
|
|
[arguments]
|
|
ctx : context pointer
|
|
data : read/write data pointer (it accepts NULL pointer)
|
|
size : byte size of data
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_record_heap(cbsl_ctx* ctx, void** data, uint64_t* size);
|
|
|
|
/*
|
|
[brief]
|
|
gets context mode.
|
|
[arguments]
|
|
ctx : context pointer
|
|
[return]
|
|
success : context mode
|
|
*/
|
|
cbsl_mode cbsl_get_mode(cbsl_ctx* ctx);
|
|
|
|
/*
|
|
[brief]
|
|
sets zstd compression level of serialized data.
|
|
[arguments]
|
|
ctx : context pointer
|
|
clevel : compression level 1-22 (zstd 1.4.0)
|
|
[return]
|
|
success : cbsl_success
|
|
fail : cbsl_error
|
|
*/
|
|
cbsl_errors cbsl_set_compression_level(cbsl_ctx* ctx, int clevel);
|
|
|
|
/*
|
|
[brief]
|
|
gets zstd compression level of serialized data.
|
|
[arguments]
|
|
ctx : context pointer
|
|
[return]
|
|
success : compression level 1-22 (zstd 1.4.0)
|
|
fail : -1
|
|
*/
|
|
int cbsl_get_compression_level(cbsl_ctx* ctx);
|
|
```
|
|
|
|
### Fortran
|
|
|
|
```fortran
|
|
!
|
|
! [brief]
|
|
! open serialized data file stream.
|
|
! [arguments]
|
|
! open_mode: specifies load/store mode
|
|
! path : data file path
|
|
! errcode : error code
|
|
! [return]
|
|
! success : return context pointer
|
|
! fail : NULL pointer
|
|
!
|
|
function cbslf_open(open_mode, path, errcode) result(ctx)
|
|
integer(4), intent(in) :: open_mode
|
|
character(*), intent(in) :: path
|
|
integer(4), intent(out), optional :: errcode
|
|
type(cbslf_context) :: ctx
|
|
end function
|
|
|
|
!
|
|
! [brief]
|
|
! close serialized data file stream.
|
|
! this subroutine calls cbslf_flush() before closing stream.
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! errcode : error code
|
|
!
|
|
subroutine cbslf_close(ctx, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
integer(4), intent(out), optional :: errcode
|
|
end subroutine
|
|
|
|
!
|
|
! [brief]
|
|
! flush file stream.
|
|
! this subroutine executes data compression and write to file stream.
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! errcode : error code
|
|
!
|
|
subroutine cbslf_flush(ctx, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
integer(4), intent(out), optional :: errcode
|
|
end subroutine
|
|
|
|
!
|
|
! [brief]
|
|
! this is a generic interface.
|
|
! the data stores with compression.
|
|
! this subroutine stores internal buffer to stored data.
|
|
! When the stored data fills enough size to compress, this subroutine calls cbslf_flush().
|
|
! [supported types]
|
|
! scalar : logical, character(*)
|
|
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! data : write data (array must be allocated)
|
|
! errcode : error code
|
|
!
|
|
interface cbslf_write(ctx, data, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
GENERIC_TYPE, intent(in) :: data
|
|
integer(4), intent(out), optional :: errcode
|
|
end interface
|
|
|
|
!
|
|
! [brief]
|
|
! this is a generic interface.
|
|
! the data loads with decompression.
|
|
! this subroutine decompresses data from a file stream, and loads from internal decompressed buffer.
|
|
! [supported types]
|
|
! scalar : logical, character(*)
|
|
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by 7-dimensional array
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! data : write data (array must be allocated)
|
|
! errcode : error code
|
|
!
|
|
interface cbslf_read(ctx, data, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
GENERIC_TYPE, intent(out) :: data
|
|
integer(4), intent(out), optional :: errcode
|
|
end interface
|
|
|
|
!
|
|
! [brief]
|
|
! this is a generic interface.
|
|
! the data loads/stores with compression/decompression.
|
|
! this subroutine calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
|
|
! [supported types]
|
|
! scalar : logical, character(*)
|
|
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! data : read/write data (array must be allocated)
|
|
! size : byte size of data
|
|
! errcode : error code (return value)
|
|
!
|
|
interface cbslf_record(ctx, data, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
GENERIC_TYPE, intent(inout) :: data
|
|
integer(4), intent(out), optional :: errcode
|
|
end interface
|
|
|
|
!
|
|
! [brief]
|
|
! this is a generic interface for allocatable array.
|
|
! the data loads/stores with compression/decompression.
|
|
! this subroutine calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
|
|
! this subroutine behaves as like as cbsl_record_heap() in C API.
|
|
! an array will be allocated on the memory if it is not allocated.
|
|
! [supported types]
|
|
! array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! data : read/write data (accepts not allocated array)
|
|
! size : byte size of data
|
|
! errcode : error code
|
|
!
|
|
interface cbslf_record_heap(ctx, data, errcode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
GENERIC_TYPE, intent(inout) :: data
|
|
integer(4), intent(out), optional :: errcode
|
|
end interface
|
|
|
|
!
|
|
! [brief]
|
|
! gets context mode.
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! errcode : error code (return value)
|
|
! [return]
|
|
! success : context mode
|
|
!
|
|
function cbslf_get_mode(ctx, errcode) result(mode)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
integer(4), intent(out), optional :: errcode
|
|
integer(4) :: mode
|
|
end function
|
|
|
|
!
|
|
! [brief]
|
|
! sets zstd compression level of serialized data.
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! clevel : compression level 1-22 (zstd 1.4.0)
|
|
! errcode : error code (return value)
|
|
!
|
|
subroutine cbslf_set_compression_level(ctx, clevel)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
ingeter(4), intent(in) :: clevel
|
|
integer(4), intent(out), optional :: errcode
|
|
end subroutine
|
|
|
|
!
|
|
! [brief]
|
|
! gets zstd compression level of serialized data.
|
|
! [arguments]
|
|
! ctx : context pointer
|
|
! [return]
|
|
! success : compression level 1-22 (zstd 1.4.0)
|
|
! fail : -1
|
|
!
|
|
function cbslf_get_compression_level(ctx, errcode) result(clevel)
|
|
type(cbslf_context), intent(in) :: ctx
|
|
integer(4), intent(out), optional :: errcode
|
|
ingeter(4), :: clevel
|
|
end function
|
|
```
|
|
|
|
## Data format
|
|
|
|
```
|
|
BDATA: binary data [1 byte]
|
|
BSIZE: total size of binary data [4 bytes]
|
|
RSIZE: rank size of a fortran array [4 bytes]
|
|
NRANK: number of rank size of a fortran array
|
|
|
|
sizeof(TYPE): gets byte size of TYPE
|
|
Array-value-type: element type of an array
|
|
```
|
|
|
|
### Header
|
|
|
|
```
|
|
[BDATA * 8]: cbsl library version (64-bit integer)
|
|
```
|
|
|
|
### C API
|
|
|
|
```
|
|
Scalar data: HEAD -> [BDATA * sizeof(Scalar)] -> TAIL
|
|
Array data : HEAD -> [BSIZE][BDATA * sizeof(Array-value-type) * BSIZE] -> TAIL
|
|
```
|
|
|
|
### Fortran API
|
|
|
|
```
|
|
Scalar data: HEAD -> [BDATA * sizeof(Scalar)] -> TAIL
|
|
Array data : HEAD -> [BSIZE][ARRAY_LOWER_BOUNDS][ARRAY_UPPER_BOUNDS][BDATA * sizeof(Array-value-type) * BSIZE] -> TAIL
|
|
|
|
ARRAY_LOWER_BOUNDS: lower bounds of a fortran array [RSIZE * NRANK]
|
|
ARRAY_UPPER_BOUNDS: upper bounds of a fortran array [RSIZE * NRANK]
|
|
```
|