Descripción

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

Vuelca los metadatos de las entradas almacenadas actualmente en la caché. Los valores en sí no son devueltos.

Parámetros

limit

Número máximo de entradas a devolver.

Pasar -1 como limit vuelca todas las entradas que la caché contiene en ese momento. Es de tener en cuenta que construir la lista completa puede consumir una cantidad considerable de memoria en una caché grande; cuando la memoria importa, es preferible recorrer las entradas por páginas con limit y offset.

offset

Número de entradas a omitir antes de empezar a recopilar. Este parámetro está disponible a partir de PECL yac 2.4.0; las versiones anteriores siempre comienzan por la primera entrada. Combinado con limit, permite recorrer por páginas una caché que contiene más entradas de las que una sola llamada puede devolver.

Valores devueltos

Un array con un elemento por cada entrada volcada. Cada elemento es a su vez un array que describe la entrada:

index: El índice de la ranura de la entrada en la tabla hash.
hash: El hash de 64 bits de la clave, utilizado para el sondeo de ranuras.
crc: La suma de comprobación CRC32 del valor almacenado, utilizada para detectar lecturas inconsistentes. 0 para las entradas empotradas, que no tienen bloque de valor.
ttl: La marca de tiempo de expiración (tiempo Unix). 0 significa que la entrada nunca expira por tiempo. Es de tener en cuenta que Yac::delete() solamente marca una entrada como expirada, por lo que las entradas eliminadas pueden seguir apareciendo en el volcado; un ttl distinto de cero situado en el pasado indica una entrada expirada o eliminada.
k_len: La longitud de la clave, en bytes.
v_len: La longitud del valor, en bytes. Para las entradas comprimidas se trata de la longitud del valor original antes de la compresión (a partir de yac 2.4.0; las versiones anteriores informaban de la longitud almacenada, ya comprimida).
c_len: Presente únicamente para las entradas comprimidas (a partir de yac 2.4.0): la longitud de la carga útil comprimida realmente almacenada en la memoria compartida, en bytes. Comparar c_len con v_len muestra cuánto ahorra la compresión en cada entrada.
size: El tamaño asignado al bloque de valor en la memoria compartida, en bytes. 0 para las entradas empotradas.
atime: La hora del último acceso (tiempo Unix), actualizada en cada Yac::get() con éxito. Cuando la caché está llena, la entrada con el atime más antiguo de entre las ranuras candidatas es la primera en ser desalojada (a partir de yac 2.4.0).
hits: Un contador de aciertos por entrada, incrementado en cada Yac::get() con éxito y reiniciado cuando la entrada es sobrescrita por un nuevo Yac::set() o Yac::add() (a partir de yac 2.4.0).
embedded: Indica si el valor se almacena directamente dentro de la ranura en lugar de en un bloque de valor separado (a partir de yac 2.4.0). Los valores pequeños — NULL, booleanos, enteros pequeños, cadenas de hasta 7 bytes y arrays vacíos — se incrustan de esta forma y no reservan memoria de valor alguna; para ellos crc y size se indican como 0.
key: La clave de la caché, sin ningún prefijo de instancia.

Ejemplos

Ejemplo #1 Ejemplo de Yac::dump()

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

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

Resultado del ejemplo anterior es similar a:

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
        )

)

Las entradas se listan en el orden de las ranuras, no en el orden en que fueron almacenadas. Las entradas empotradas (escalares cortos conservados dentro de la propia ranura) tienen crc y size a cero; las entradas almacenadas en un bloque de valor separado llevan su suma de comprobación y el tamaño del bloque, y las entradas comprimidas llevan además c_len.

Ejemplo #2 Recorrido por páginas de una caché grande

limit limita cuántas entradas devuelve una sola llamada, y offset omite esa cantidad de entradas antes de empezar a recopilar, de modo que ambos pueden combinarse para recorrer por páginas una caché que contiene más entradas de las que una sola llamada puede devolver.

<?php
$yac = new Yac();

// llena la caché con 250 entradas
for ($i = 0; $i < 250; $i++) {
    $yac->set("key$i", $i);
}

$page_size = 100;
$page_num  = 2;

// omite las 100 primeras entradas y devuelve las 100 siguientes (página 2)
$page = $yac->dump($page_size, $page_size * ($page_num - 1));

var_dump(count($page));
?>

Resultado del ejemplo anterior es similar a:

int(100)

Se devuelven menos entradas de las solicitadas cuando la caché contiene menos entradas de las que abarca la página pedida, y se devuelve un array vacío en cuanto el desplazamiento apunta más allá de la última ranura ocupada.

Véase también

Yac::info() - Estado del caché