3.8. Storages

Storages are vectors of identical objects that are used as data storage areas for scalars, vectors, matrices, tensors, and similar structures.

Data in a storage is rarely accessed directly, but often accessed through an IDX object. Several IDXs can point to the same data in a storage, allowing access of the data in multiple ways simultaneously.
The data in a storage can reside in memory (a memory storage) or on disk (a memory-mapped storage). Disk files can be memory mapped into a storage and accessed element by element or byte by byte through storage or IDX access functions.
Storages can be resized/reallocated without adverse effects on the IDX that point to them.

3.8.0. Storage Creation and Allocation

Each of the following functions has several names. For example, int-storage can also be invoked with new_i32_storage as well as new-int-storage . However, the names described below are preferred.

3.8.0.0. (float-storage [n])

[DE] (storage.c)

Creates a storage of class |FSTORAGE| whose elements are 4-byte floats. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.1. (double-storage [n])

[DE] (storage.c)

Creates a storage of class |DSTORAGE| whose elements are double precision floats (8 bytes). If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.2. (int-storage [n])

[DE] (storage.c)

Creates a storage of class |I32STORAGE| whose elements are 4 byte siged integers. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.3. (short-storage [n])

[DE] (storage.c)

Creates a storage of class |I16STORAGE| whose elements are 2 byte siged integers. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.4. (byte-storage [n])

[DE] (storage.c)

Creates a storage of class |I8STORAGE| whose elements are single-byte singed integers. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.5. (ubyte-storage [n])

[DE] (storage.c)

Creates a storage of class |U8STORAGE| whose elements are single-byte unsinged integers. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.6. (gptr-storage [n])

[DE] (storage.c)

Creates a storage of class |GPTRSTORAGE| whose elements are generic memory pointers. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.7. (atom-storage [n])

[DE] (storage.c)

Creates a storage of class |ATSTORAGE| whose elements are Lisp objects. If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap.

3.8.0.8. (packed-storage [n])

[DE] (storage.c)

Creates a storage of class |PSTORAGE| whose elements are packed fixed point numbers (one-byte signed numbers with 4 bit integer part and 4 bit fractional part). If n is present, n elements are allocated in memory and initialized to 0 (or NIL). If n is not present, an unsized storage is returned that can be subsequently allocated in memory with storage_malloc, storage_malloc_nc, or memory-mapped from a file with storage_mmap. This type of storage is somewhat obsolete, but is there for backward compatibility with SN2.x.

3.8.1. Storage Allocation

3.8.1.0. (storage-malloc srg n)

[DE] (storage.c)

Set the size of storage srg to n , allocate n elements in memory, and clear the content (to 0 or NIL depending on the type of storage). Storage srg must be unsized (as returned by new-xxx-storage ).

3.8.1.1. (storage-malloc-nc srg n)

[DE] (storage.c)

Set the size of storage srg to n , allocate n elements in memory. The elements are not cleared to save time. Storage srg must be unsized (as returned by new-xxx-storage ).

3.8.1.2. (storage-realloc srg n)

[DE] (storage.c)

Change the size of storage srg to n , and reallocate n elements in memory. IDXs that points to srg are unaffected (i.e. they point to the right place and their content data is unchanged). The newly allocated data segment is initialize to 0 or NIL.

3.8.1.3. (storage-realloc-nc srg n)

[DE] (storage.c)

3.8.1.4. (storage-mmap srg file offset)

[DE] (storage.c)

maps the content of file file into memory. file can be either a file descriptor or a string containing a filename. Each element of the file starting at byte offset is made accessible through the corresponding element of the storage srg . Storage of Lisp objects ( |ATSTORAGE| cannot be memory mapped. Mapped storages are read-only. Whether a storage is read-only can be determined with the function writablep .

3.8.2. Storage Access

Storage elements can be read and set as if the storage were an IDX with one dimension (a vector). In other words (s 3) returns the value of element 3 of storage s . (s 3 5) sets it to 5.

3.8.3. Miscellaneous Storage Functions

3.8.3.0. (storage-save srg file)

[DX]

save the content of storage srg into file file . file may be a string containing a filename or a file descriptor. Data is written raw, without a header, and in the native format of the machine (multibyte elements will not be portable between big and small-endian machines).

3.8.3.1. (storage-load srg file)

[DX]

load storage srg with the content of file file . file may be a string containing a filename or a file descriptor.

3.8.3.2. (storagep srg)

[DX]

return true is srg is a storage, and nil otherwise.

3.8.3.3. (writablep srg)

[DX]

return true if srg is writable, and nile otherwise. Memory mapped storages are generally not writable.

3.8.3.4. (storage-read-only srg)

[DX]

marks storage srg as being read-only. No Lisp function can write into it after this.

3.8.3.5. (storage-size srg)

[DX]

return the number of element in storage srg . Return 0 if the storage is unsized.

3.8.3.6. (storage-clear srg)

[DX]

Fills up all the element of storage srg with 0 or NIL.