---
name: Storable
runtime: pp
source: src/native/Storable/pp.rs
---
```{index} single: Storable; Perl module (pp runtime)
```

# Storable

Native implementation of Storable

Provides serialization/deserialization functions for Perl data structures.
This module implements a subset of Storable's functionality compatible with
common use cases.

# Synopsis

    use Storable qw(freeze thaw dclone store retrieve);

    my $frozen = freeze(\%hash);
    my $thawed = thaw($frozen);

    store(\%hash, '/tmp/data.storable');
    my $data = retrieve('/tmp/data.storable');

    my $copy = dclone(\@deep_structure);

# Functions

## freeze

Serialize a Perl data structure into a binary string (in-memory). Uses native byte order.

```perl
use Storable 'freeze';
my $serialized = freeze(\%hash);
```

## nfreeze

Serialize a Perl data structure into a binary string using network (big-endian)
byte order for portability across architectures.

```perl
use Storable 'nfreeze';
my $portable = nfreeze(\@array);
```

## thaw

Deserialize a binary string (produced by freeze or nfreeze) back into a Perl data structure.

```perl
use Storable 'thaw';
my $data = thaw($serialized);
```

## dclone

Deep-clone a Perl data structure (freeze + thaw in one step). Handles circular references.

```perl
use Storable 'dclone';
my $copy = dclone(\%original);
```

## store

Serialize a data structure and write it to a file. Uses native byte order.

```perl
use Storable 'store';
store(\%hash, '/tmp/data.storable');
```

## nstore

Serialize a data structure and write it to a file using network byte order.

## retrieve

Read a file written by store/nstore and deserialize it back into a data structure.

```perl
use Storable 'retrieve';
my $data = retrieve('/tmp/data.storable');
```

## store_fd / nstore_fd

Serialize a data structure to an open filehandle (native or network byte order).

## fd_retrieve

Deserialize a data structure from an open filehandle.

## lock_store / lock_nstore / lock_retrieve

Locking variants of store, nstore, and retrieve (currently aliases without actual locking).

## file_magic

Return a hash describing the Storable file format magic of a given file.

## read_magic

Return a hash describing the Storable format magic from a binary string header.

## stack_depth / stack_depth_hash / recursion_limit / recursion_limit_hash

Get or set the maximum recursion depth for serialization/deserialization.

# Serialization Format

We use a custom binary format optimized for PetaPerl's Sv types:
- Type tag (1 byte)
- Length-prefixed data where applicable
- Recursive handling of nested structures

# Network Byte Order

Functions prefixed with 'n' (nstore, nfreeze) use big-endian byte order
for portability across different architectures. Regular functions use
native byte order for speed on local storage.