Shard Struct Reference

Represents a memory-mapped SafeTensors file (shard). More...

#include <safetensors_loader.h>

Collaboration diagram for Shard:

Public Member Functions
	Shard (const std::string &fp)
	Construct and memory-map a shard file.
	~Shard ()
	Destructor. Cleans up memory mapping and file handles.
	Shard (Shard &&other) noexcept
	Move constructor.
Shard &	operator= (Shard &&other) noexcept
	Move assignment operator.
const uint8_t *	get_tensor_raw_data (size_t local_offset, size_t n_bytes) const
	Get a pointer to the raw tensor data within this shard.

Public Attributes
std::string	file_path
	Path to the shard file.
void *	mapped_data = nullptr
	Pointer to the memory-mapped data.
size_t	file_size = 0
	Size of the mapped file in bytes.
uint64_t	metadata_size = 0
	Size of the metadata block in bytes.
const uint8_t *	metadata_ptr = nullptr
	Pointer to the start of the metadata block.
const uint8_t *	tensor_data_block_ptr = nullptr
	Pointer to the start of the tensor data block.
int	fd_ = -1

Detailed Description

Represents a memory-mapped SafeTensors file (shard).

Handles opening, memory-mapping, and cleanup for a single SafeTensors file. Used internally by SafeTensorsLoader to support sharded models.

Definition at line 42 of file safetensors_loader.h.

Constructor & Destructor Documentation

Shard() [1/2]

Shard::Shard ( const std::string &  fp )

explicit

Construct and memory-map a shard file.

Parameters

fp	Path to the shard file.

Exceptions

std::runtime_error

on failure.

Definition at line 85 of file safetensors_loader.cpp.

                                : file_path(fp) {
    Logger::info("Shard: Initializing for file: " + file_path);
#ifdef _WIN32
    file_handle_ = CreateFileA(file_path.c_str(), GENERIC_READ, FILE_SHARE_READ,
                               NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
    if (file_handle_ == INVALID_HANDLE_VALUE) {
        throw std::runtime_error("Shard: Failed to open file (Windows): " + file_path + " Error: " + std::to_string(GetLastError()));
    }
 
    LARGE_INTEGER size_li;
    if (!GetFileSizeEx(file_handle_, &size_li)) {
        CloseHandle(file_handle_);
        file_handle_ = INVALID_HANDLE_VALUE; 
        throw std::runtime_error("Shard: Failed to get file size (Windows): " + file_path);
    }
    file_size = static_cast<size_t>(size_li.QuadPart);
    if (file_size == 0) { 
        CloseHandle(file_handle_);
        file_handle_ = INVALID_HANDLE_VALUE;
        throw std::runtime_error("Shard: File is empty: " + file_path);
    }
 
    mapping_handle_ = CreateFileMapping(file_handle_, NULL, PAGE_READONLY, 0, 0, NULL);
    if (mapping_handle_ == NULL) {
        CloseHandle(file_handle_);
        file_handle_ = INVALID_HANDLE_VALUE;
        throw std::runtime_error("Shard: Failed to create file mapping (Windows): " + file_path + " Error: " + std::to_string(GetLastError()));
    }
 
    mapped_data = MapViewOfFile(mapping_handle_, FILE_MAP_READ, 0, 0, file_size);
    if (mapped_data == nullptr) {
        CloseHandle(mapping_handle_);
        mapping_handle_ = NULL;
        CloseHandle(file_handle_);
        file_handle_ = INVALID_HANDLE_VALUE;
        throw std::runtime_error("Shard: Failed to map view of file (Windows): " + file_path + " Error: " + std::to_string(GetLastError()));
    }
#else // POSIX
    fd_ = open(file_path.c_str(), O_RDONLY);
    if (fd_ == -1) {
        throw std::runtime_error("Shard: Failed to open file: " + file_path + " Error: " + strerror(errno));
    }
 
    struct stat sb;
    if (fstat(fd_, &sb) == -1) {
        close(fd_);
        fd_ = -1; 
        throw std::runtime_error("Shard: Failed to get file size: " + file_path + " Error: " + strerror(errno));
    }
    file_size = sb.st_size;
    if (file_size == 0) { 
        close(fd_);
        fd_ = -1;
        throw std::runtime_error("Shard: File is empty: " + file_path);
    }
 
    mapped_data = mmap(NULL, file_size, PROT_READ, MAP_SHARED, fd_, 0);
    if (mapped_data == MAP_FAILED) {
        close(fd_);
        fd_ = -1;
        mapped_data = nullptr; 
        throw std::runtime_error("Shard: Failed to memory map file: " + file_path + " Error: " + strerror(errno));
    }
#endif
    Logger::debug("Shard: Successfully mapped file: " + file_path + ", size: " + std::to_string(file_size));
 
    if (file_size < 8) { 
        throw std::runtime_error("Shard: File too small (" + std::to_string(file_size) + " bytes) to be a valid SafeTensors shard (min 8 bytes for metadata length): " + file_path);
    }
    metadata_size = *reinterpret_cast<const uint64_t*>(mapped_data);
    
    if (metadata_size == 0) {
        throw std::runtime_error("Shard: Metadata size is 0 in file header: " + file_path);
    }
    if (8 + metadata_size > file_size) {
        throw std::runtime_error("Shard: Declared metadata size (" + std::to_string(metadata_size) + ") plus header (8 bytes) exceeds file size (" + std::to_string(file_size) + ") in: " + file_path);
    }
    metadata_ptr = static_cast<const uint8_t*>(mapped_data) + 8;
    tensor_data_block_ptr = metadata_ptr + metadata_size;
    Logger::debug("Shard: Metadata size from header: " + std::to_string(metadata_size) + " for " + file_path);
}

References Logger::debug(), fd_, file_path, file_size, Logger::info(), mapped_data, metadata_ptr, metadata_size, and tensor_data_block_ptr.

~Shard()

Shard::~Shard

(

)

Destructor. Cleans up memory mapping and file handles.

Definition at line 167 of file safetensors_loader.cpp.

              {
    Logger::debug("Shard: Cleaning up for file: " + (file_path.empty() ? "(moved or uninitialized)" : file_path) ); 
#ifdef _WIN32
    if (mapped_data != nullptr) {
        if (!UnmapViewOfFile(mapped_data)) {
            Logger::error("Shard: Failed to unmap view of file (Windows) for \"" + file_path + "\" Error: " + std::to_string(GetLastError()));
        }
    }
    if (mapping_handle_ != NULL) {
        if (!CloseHandle(mapping_handle_)) {
             Logger::error("Shard: Failed to close mapping handle (Windows) for \"" + file_path + "\" Error: " + std::to_string(GetLastError()));
        }
    }
    if (file_handle_ != INVALID_HANDLE_VALUE) {
        if (!CloseHandle(file_handle_)) {
            Logger::error("Shard: Failed to close file handle (Windows) for \"" + file_path + "\" Error: " + std::to_string(GetLastError()));
        }
    }
    mapped_data = nullptr; 
    file_handle_ = INVALID_HANDLE_VALUE; 
    mapping_handle_ = NULL; 
#else // POSIX
    if (mapped_data != nullptr && mapped_data != MAP_FAILED) {
        if (munmap(mapped_data, file_size) == -1) {
            Logger::error("Shard: Failed to munmap file: \"" + file_path + "\" Error: " + strerror(errno));
        }
    }
    if (fd_ != -1) {
        if (close(fd_) == -1) {
             Logger::error("Shard: Failed to close file descriptor for \"" + file_path + "\" Error: " + strerror(errno));
        }
    }
    mapped_data = nullptr;
    fd_ = -1;
#endif
}

References Logger::debug(), Logger::error(), fd_, file_path, file_size, and mapped_data.

Shard() [2/2]

Shard::Shard ( Shard &&  other )

noexcept

Move constructor.

Definition at line 204 of file safetensors_loader.cpp.

    : file_path(std::move(other.file_path)),
      mapped_data(other.mapped_data),
      file_size(other.file_size),
      metadata_size(other.metadata_size),
      metadata_ptr(other.metadata_ptr),
      tensor_data_block_ptr(other.tensor_data_block_ptr)
#ifdef _WIN32
      , file_handle_(other.file_handle_)
      , mapping_handle_(other.mapping_handle_)
#else
      , fd_(other.fd_)
#endif
{
    other.mapped_data = nullptr;
    other.file_size = 0;
    other.metadata_size = 0;
    other.metadata_ptr = nullptr;
    other.tensor_data_block_ptr = nullptr;
#ifdef _WIN32
    other.file_handle_ = INVALID_HANDLE_VALUE;
    other.mapping_handle_ = NULL;
#else
    other.fd_ = -1;
#endif
}

Member Function Documentation

get_tensor_raw_data()

const uint8_t * Shard::get_tensor_raw_data	(	size_t	local_offset,
		size_t	n_bytes
	)		const

Get a pointer to the raw tensor data within this shard.

Parameters

local_offset	Offset from the start of the tensor data block.
n_bytes	Number of bytes to access.

Returns

Pointer to the tensor data.

Exceptions

std::out_of_range

if the requested range is invalid.

Definition at line 261 of file safetensors_loader.cpp.

                                                                                   {
#ifdef _WIN32
    if (!mapped_data || mapped_data == NULL || !tensor_data_block_ptr) { 
#else // POSIX
    if (!mapped_data || mapped_data == MAP_FAILED || !tensor_data_block_ptr) { 
#endif
        throw std::logic_error("Shard not properly mapped or initialized to get tensor data: " + file_path);
    }
    const uint8_t* data_start = tensor_data_block_ptr + local_offset;
    const uint8_t* shard_data_block_end = tensor_data_block_ptr + (file_size - (8 + metadata_size));
 
    if (data_start < tensor_data_block_ptr || data_start + n_bytes > shard_data_block_end || n_bytes > (file_size - (8 + metadata_size))) { 
        throw std::out_of_range(
            "Tensor data (local_offset: " + std::to_string(local_offset) +
            ", n_bytes: " + std::to_string(n_bytes) +
            ") out of bounds for data block of shard: " + file_path +
            ". Shard data block size: " + std::to_string(file_size - (8 + metadata_size)) + " bytes."
        );
    }
    return data_start;
}

References file_path, file_size, mapped_data, metadata_size, and tensor_data_block_ptr.

Referenced by SafeTensorsLoader::get_tensor_bytes().

operator=()

Shard & Shard::operator= ( Shard &&  other )

noexcept

Move assignment operator.

Definition at line 231 of file safetensors_loader.cpp.

                                              {
    if (this != &other) {
        this->~Shard(); 
        file_path = std::move(other.file_path);
        mapped_data = other.mapped_data;
        file_size = other.file_size;
        metadata_size = other.metadata_size;
        metadata_ptr = other.metadata_ptr;
        tensor_data_block_ptr = other.tensor_data_block_ptr;
#ifdef _WIN32
        file_handle_ = other.file_handle_;
        mapping_handle_ = other.mapping_handle_;
#else
        fd_ = other.fd_;
#endif
        other.mapped_data = nullptr;
        other.file_size = 0; 
        other.metadata_size = 0;
        other.metadata_ptr = nullptr;
        other.tensor_data_block_ptr = nullptr;
#ifdef _WIN32
        other.file_handle_ = INVALID_HANDLE_VALUE;
        other.mapping_handle_ = NULL;
#else
        other.fd_ = -1;
#endif
    }
    return *this;
}

Member Data Documentation

fd_

int Shard::fd_ = -1

File descriptor for memory mapping

Definition at line 77 of file safetensors_loader.h.

Referenced by Shard(), and ~Shard().

file_path

std::string Shard::file_path

Path to the shard file.

Definition at line 46 of file safetensors_loader.h.

Referenced by get_tensor_raw_data(), SafeTensorsLoader::parse_shard_metadata(), Shard(), and ~Shard().

file_size

size_t Shard::file_size = 0

Size of the mapped file in bytes.

Definition at line 56 of file safetensors_loader.h.

Referenced by get_tensor_raw_data(), Shard(), and ~Shard().

mapped_data

void* Shard::mapped_data = nullptr

Pointer to the memory-mapped data.

Definition at line 51 of file safetensors_loader.h.

Referenced by get_tensor_raw_data(), Shard(), and ~Shard().

metadata_ptr

const uint8_t* Shard::metadata_ptr = nullptr

Pointer to the start of the metadata block.

Definition at line 66 of file safetensors_loader.h.

Referenced by SafeTensorsLoader::parse_shard_metadata(), and Shard().

metadata_size

uint64_t Shard::metadata_size = 0

Size of the metadata block in bytes.

Definition at line 61 of file safetensors_loader.h.

Referenced by get_tensor_raw_data(), SafeTensorsLoader::parse_shard_metadata(), and Shard().

tensor_data_block_ptr

const uint8_t* Shard::tensor_data_block_ptr = nullptr

Pointer to the start of the tensor data block.

Definition at line 71 of file safetensors_loader.h.

Referenced by get_tensor_raw_data(), and Shard().

---

The documentation for this struct was generated from the following files:

• safetensors_loader.h
• safetensors_loader.cpp