Home/ Manual/ yac / yac/ Yac::dump

Yac::dump

PHP function Edit on GitHub ✎

(PECL yac >= 1.0.0)

Dump cache entries for inspection

Description

Yac::dump(int $limit = 100, int $offset = 0): array

Dumps metadata of the entries currently stored in the cache. The values themselves are not returned.

Parameters

limit

Maximum number of entries to return.

Passing -1 as limit dumps every entry the cache currently holds. Note that building the full list may use a considerable amount of memory for a large cache; when memory matters, page through the entries with limit and offset instead.

offset

Number of entries to skip before collecting. This parameter is available as of PECL yac 2.4.0; earlier versions always start from the first entry. Combined with limit, it can be used to page through a cache that holds more entries than one call may return.

Return Values

An array with one element per dumped entry. Each element is itself an array describing the entry:

index: The slot index of the entry in the hash table.
hash: The 64-bit hash of the key, used for slot probing.
crc: The CRC32 checksum of the stored value, used to detect torn reads. 0 for embedded entries, which have no value block.
ttl: The expiration timestamp (Unix time). 0 means the entry never expires by time. Note that Yac::delete only marks an entry expired, so deleted entries can still show up in the dump; a non-zero ttl in the past indicates an expired or deleted entry.
k_len: The length of the key, in bytes.
v_len: The length of the value, in bytes. For compressed entries this is the length of the original value before compression (as of yac 2.4.0; earlier versions reported the stored, compressed length).
c_len: Only present for compressed entries (as of yac 2.4.0): the length of the compressed payload actually stored in shared memory, in bytes. Comparing c_len with v_len shows how much compression saves per entry.
size: The allocated size of the value block in shared memory, in bytes. 0 for embedded entries.
atime: The last access time (Unix time), updated on each successful Yac::get. When the cache is full, the entry with the oldest atime among the candidate slots is evicted first (as of yac 2.4.0).
hits: A per-entry hit counter, bumped on each successful Yac::get and reset when the entry is overwritten by a new Yac::set or Yac::add (as of yac 2.4.0).
embedded: Whether the value is stored directly inside the slot instead of in a separate value block (as of yac 2.4.0). Small values — NULL, booleans, small integers, strings of up to 7 bytes and empty arrays — are embedded this way and allocate no value memory at all; for them crc and size are reported as 0.
key: The cache key, without any instance prefix.

Examples

Yac::dump example

php

<?php
$yac = new Yac();
$yac->set("foo", "bar");
$yac->set("baz", "qux");

print_r($yac->dump());
?>

The above example will output something similar to:

output

Array
(
    [0] => Array
        (
            [index] => 12345
            [hash] => 14463105906481965911
            [crc] => 0
            [ttl] => 0
            [k_len] => 3
            [v_len] => 3
            [size] => 0
            [atime] => 1725955200
            [hits] => 0
            [embedded] => 1
            [key] => foo
        )

    [1] => Array
        (
            [index] => 12987
            [hash] => 15132029420525657053
            [crc] => 0
            [ttl] => 0
            [k_len] => 3
            [v_len] => 3
            [size] => 0
            [atime] => 1725955200
            [hits] => 0
            [embedded] => 1
            [key] => baz
        )

)

Entries are listed in slot order, not in the order they were stored. Embedded entries (short scalars kept inside the slot itself) have crc and size set to zero; entries stored in a separate value block carry their checksum and block size, and compressed entries additionally carry c_len.

Paging through a large cache

limit bounds how many entries a single call returns, and offset skips that many entries before collecting, so the two can be combined to page through a cache that holds more entries than one call may return.

php

<?php
$yac = new Yac();

// fill the cache with 250 entries
for ($i = 0; $i < 250; $i++) {
    $yac->set("key$i", $i);
}

$page_size = 100;
$page_num  = 2;

// skip the first 100 entries and return the next 100 (page 2)
$page = $yac->dump($page_size, $page_size * ($page_num - 1));

var_dump(count($page));
?>