PHP Manual: Yac::dump

Description

public function 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

Example #1 Yac::dump() example

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

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

The above example will output something similar to:

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.

Example #2 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
$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));
?>

The above example will output something similar to:

int(100)

Fewer entries than requested are returned when the cache holds fewer entries than the requested page covers, and an empty array is returned once the offset points past the last occupied slot.

Yac::dump

Description

Parameters

Return Values

Examples

See Also