From e54cf1d91b49a382b315407aeaf2e0e2082bea0c Mon Sep 17 00:00:00 2001 From: lacatoire Date: Thu, 27 Aug 2026 17:47:55 +0200 Subject: [PATCH] [Sync-En] yac: sync the Yac extension documentation with EN --- reference/yac/book.xml | 56 ++++++- reference/yac/ini.xml | 77 +++++++--- reference/yac/setup.xml | 103 +++++++++++-- reference/yac/yac/add.xml | 113 +++++++++----- reference/yac/yac/construct.xml | 64 +++++--- reference/yac/yac/delete.xml | 105 ++++++++++--- reference/yac/yac/dump.xml | 259 ++++++++++++++++++++++++++++++-- reference/yac/yac/flush.xml | 53 +++++-- reference/yac/yac/get.xml | 99 +++++++++--- reference/yac/yac/getter.xml | 61 ++++++-- reference/yac/yac/info.xml | 154 +++++++++++++++++-- reference/yac/yac/set.xml | 81 +++++++--- reference/yac/yac/setter.xml | 61 ++++++-- 13 files changed, 1065 insertions(+), 221 deletions(-) diff --git a/reference/yac/book.xml b/reference/yac/book.xml index ee59fbb9b1..f41e936345 100644 --- a/reference/yac/book.xml +++ b/reference/yac/book.xml @@ -1,7 +1,5 @@ - - - + @@ -10,9 +8,55 @@ &reftitle.intro; - - Yac (Otro caché), es un caché de datos de usuario de memoria compartida sin bloqueo, podría utilizarse para reemplazar el APC, el memcache local. - + + Yac (Yet Another Cache) es una caché de datos de usuario en memoria + compartida y sin bloqueos, que puede utilizarse para reemplazar a APC + o a un memcached local. + + + Yac almacena los datos en memoria compartida, lo que los hace visibles + para todos los procesos de trabajo de PHP de la misma máquina sin + ninguna comunicación entre procesos. En lugar de bloqueos, Yac se basa + en actualizaciones atómicas de las ranuras junto con unos pocos sondeos + de colisión, de modo que un fallo de caché nunca bloquea una petición y + una escritura concurrente puede provocar, en el peor de los casos, un + almacenamiento fallido o una lectura perdida que quien la invoca puede + simplemente reintentar. + + + Al no haber bloqueos ni comunicación entre procesos en la ruta de + acceso, una lectura es esencialmente una búsqueda hash en memoria + compartida. Como resultado, Yac es extremadamente rápida, con una + latencia de lectura del orden de microsegundos, y su rendimiento puede + escalar con el número de procesos de trabajo mientras las escrituras se + repartan entre distintas claves. + + + Dado que Yac sacrifica garantías de corrección a cambio de velocidad y + rendimiento, resulta más adecuada para datos que son costosos de + producir pero fáciles de recrear: fragmentos de página, instantáneas de + configuración, respuestas pequeñas de servicios y otras cachés locales. + No debería utilizarse como almacén de referencia para datos + irremplazables. + + + A partir de yac 2.4.0, los valores escalares pequeños — + NULL, booleanos, enteros, cadenas cortas de hasta + 7 bytes y arrays vacíos — se almacenan directamente dentro de la ranura + hash en lugar de en un bloque de valor separado («valores + incrustados»), lo que elimina la reserva de memoria del valor y la + copia del bloque en cada acceso, mejorando significativamente el + rendimiento al tiempo que reduce el uso de memoria. La versión 2.4.0 + también cambió el motor de compresión de FastLZ a LZ4, haciendo que las + lecturas comprimidas sean varias veces más rápidas. + + + + La memoria compartida solo es visible dentro de una misma máquina. + Para compartir una caché entre varios servidores, se debe utilizar en + su lugar una caché en red como Memcached o Redis. + + &reference.yac.setup; diff --git a/reference/yac/ini.xml b/reference/yac/ini.xml index f62be374b4..58c1b631ef 100644 --- a/reference/yac/ini.xml +++ b/reference/yac/ini.xml @@ -1,7 +1,5 @@ - - - +
&reftitle.runtime; @@ -76,9 +74,14 @@ int - - - + + Los valores serializados que superan este número de bytes se + comprimen antes de almacenarse (actualmente con LZ4). Se debe + establecer a -1 (el valor predeterminado) para + desactivar por completo la compresión. Comprimir valores grandes + ahorra memoria compartida a costa de algo de CPU tanto al almacenar + como al recuperar. + @@ -87,9 +90,10 @@ int - - - + + Reservada para depuración. A partir de Yac 2.4.0 esta directiva + está registrada pero no tiene ningún efecto. + @@ -98,9 +102,10 @@ int - - - + + Indica si Yac está activado. Si está desactivado, crear una + instancia de Yac lanza una excepción. + @@ -109,9 +114,13 @@ int - - - + + Indica si Yac está activado al ejecutarse bajo la SAPI + CLI. Está desactivado de forma predeterminada + porque los scripts de línea de comandos suelen iniciarse y + detenerse de inmediato, y el segmento de memoria compartida se + crearía en vano. + @@ -120,9 +129,15 @@ string - - - + + Cantidad de memoria compartida utilizada para las ranuras de la + tabla hash que contienen las claves y la información de control. + Cada ranura es una estructura de tamaño fijo, de modo que este + valor determina cuántos elementos pueden gestionarse a la vez. El + valor predeterminado es 4M. Yac divide esta + zona en segmentos; el tamaño de segmento es 4M, por lo que este + valor debe ser un múltiplo de 4M. + @@ -131,9 +146,17 @@ string - - - + + Serializador utilizado para convertir valores PHP arbitrarios en + bytes antes de almacenarlos. Los valores permitidos son + php (el predeterminado), + json, igbinary y + msgpack. Los tres últimos requieren que la + extensión se haya compilado con el soporte correspondiente. Los + serializadores binarios, como igbinary y + msgpack, suelen ser más rápidos y producen + datos más pequeños que php. + @@ -142,9 +165,15 @@ string - - - + + Cantidad de memoria compartida utilizada para almacenar los + valores propiamente dichos. El valor predeterminado es + 64M. Yac reserva esta zona en segmentos de 4M + cada uno, por lo que este valor debe ser un múltiplo de + 4M. Cuando la zona está llena, las entradas + usadas menos recientemente se eliminan para hacer sitio a las + nuevas. + diff --git a/reference/yac/setup.xml b/reference/yac/setup.xml index d09379f804..d82d2c5d19 100644 --- a/reference/yac/setup.xml +++ b/reference/yac/setup.xml @@ -1,31 +1,104 @@ - - - + &reftitle.setup;
&reftitle.required; - - - + + No se requiere ninguna biblioteca externa. +
&reftitle.install; - + + Yac se puede instalar de tres maneras: mediante PECL, mediante PIE o + compilándolo a partir del código fuente. + + &pecl.moved; - - + + &pecl.info; &url.pecl.package;yac. - - + + &pecl.windows.download.avail; - + + + Instalación de Yac con PECL + + + + + + A partir de Yac 2.3.2, la extensión se puede instalar con + &link.pie;, el instalador de extensiones de PHP, ejecutando lo + siguiente en la línea de comandos. + + + Instalación de Yac con PIE + + + + + + Los serializadores opcionales se pueden activar en el momento de la instalación: + + + Instalación de Yac con PIE y un serializador + + + + + + El código fuente está alojado en + GitHub. Para + compilar la extensión a partir del código fuente, se debe ejecutar lo + siguiente en la línea de comandos, sustituyendo las rutas por las de la + instalación local de PHP. + + + Compilación de Yac a partir del código fuente + + + + + + Están disponibles las siguientes opciones de configure: + + + Los valores se comprimen con LZ4 antes de ser almacenados. El motor de + compresión LZ4 se introdujo en Yac 2.4.0, en sustitución del anterior + FastLZ. De forma predeterminada, Yac utiliza la copia de LZ4 incluida con la + extensión; no se necesita ningún indicador adicional. Para enlazar en su lugar + con la biblioteca LZ4 del sistema, se utiliza la opción + , que + requiere que estén instalados la cabecera lz4.h y + liblz4. + + + Se pueden compilar serializadores alternativos con + , + o + , que registran la + extensión correspondiente como una dependencia opcional. El serializador + utilizado en tiempo de ejecución se selecciona con la directiva ini + yac.serializer. +
@@ -35,9 +108,9 @@
&reftitle.resources; - - - + + Esta extensión no define ningún tipo de recurso. +
diff --git a/reference/yac/yac/add.xml b/reference/yac/yac/add.xml index 002811e9eb..78a4c294a1 100644 --- a/reference/yac/yac/add.xml +++ b/reference/yac/yac/add.xml @@ -1,29 +1,30 @@ - - - + Yac::add - Guardar en caché + Almacena un valor sin sobrescribir uno existente &reftitle.description; public boolYac::add - stringkeys + stringarraykeys mixedvalue intttl0 public boolYac::add - arraykey_vals + arrayvalues + intttl0 - - Añadir un artículo al caché. - + + Almacena un valor en la caché. A diferencia de Yac::set, + no sobrescribe una entrada existente que siga siendo válida; en ese caso el + almacenamiento es rechazado. + @@ -32,25 +33,30 @@ keys - - &string; clave - + + Una clave de tipo string, o un array de pares + clave => valor que se almacenan en una sola llamada. + value - - valor mixto, Todo tipo de valor php podría ser almacenado excepto &resource; - + + El valor a almacenar. Puede almacenarse cualquier tipo de PHP excepto + resource. Solo se utiliza en la forma de clave única; cuando + keys es un array, este argumento es en su lugar el + parámetro opcional ttl. + ttl - - tiempo de expiración - + + Tiempo de vida en segundos. 0 significa que la entrada + nunca expira por tiempo. + @@ -58,26 +64,65 @@ &reftitle.returnvalues; + + Devuelve &true; en caso de éxito, &false; en caso de fallo. El almacenamiento + también es rechazado (devolviendo &false;) cuando la clave ya existe y no ha + expirado. + + + + Yac almacena las entradas sin bloqueos. Bajo una fuerte contención, un + almacenamiento puede fallar de forma transitoria; si el valor debe acabar + siendo almacenado, hay que reintentarlo: + +add("key", "value")) { + // reintento en caso de fallo transitorio +} +?> +]]> + + + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::add</methodname> + +add("foo", "bar")); // bool(true) +var_dump($yac->add("foo", "baz")); // bool(false): "foo" ya existe + +// ttl en segundos; 0 (el valor predeterminado) significa que la entrada nunca expira +$yac->add("short-lived", "value", 5); +sleep(6); +var_dump($yac->get("short-lived")); // bool(false): expirado + +// almacena varios pares clave => valor en una sola llamada, con un ttl +$yac->add(array("a" => 1, "b" => 2), 60); +?> +]]> + + + + + + &reftitle.seealso; - &boolean;, &true; en caso de éxito, &false; en caso de fallar. - - - Yac::add puede fallar si el casillero no se puede obtener, - así que, si necesitas que el valor se almacene correctamente, puedes escribir códigos como: - - Asegúrate de que el artículo se almacene - - set("key", "value")); - ]]> - - - - + + Yac::set + Yac::get + Yac::delete + - - - + @@ -15,10 +13,12 @@ public Yac::__construct stringprefix"" - - se utiliza un prefijo para preparar las claves, esto podría utilizarse para evitar conflictos entre aplicaciones. - - + + Crea una nueva instancia de Yac. El + prefix opcional se antepone a cada clave que almacena + esta instancia, lo que permite que varias aplicaciones o cachés en la misma + máquina utilicen nombres de clave coincidentes sin que colisionen. + @@ -27,31 +27,49 @@ prefix - - Prefijo &string; - + + Un prefijo de clave, de hasta 48 bytes (YAC_MAX_KEY_LEN). + - - - &reftitle.errors; + + &reftitle.seealso; - Lanza una Exception si Yac no está habilitado. Lanza - Exception si prefix excede - la longitud máxima de clave de 48 (YAC_MAX_KEY_LEN) bytes. + + Yac::set + Yac::get + diff --git a/reference/yac/yac/delete.xml b/reference/yac/yac/delete.xml index ff40f44222..15f961fef4 100644 --- a/reference/yac/yac/delete.xml +++ b/reference/yac/yac/delete.xml @@ -1,12 +1,10 @@ - - - + Yac::delete - Eliminar los artículos de la memoria caché + Elimina elementos de la caché @@ -14,11 +12,26 @@ public boolYac::delete stringarraykeys - intttl + intdelay0 - - retira los artículos de la memoria caché - + + Elimina uno o varios elementos de la caché. + + + + La eliminación se implementa marcando la entrada como caducada en lugar + de liberar su ranura: la entrada deja de poder leerse de inmediato, pero + la ranura permanece ocupada hasta que se almacena de nuevo la misma clave + o hasta que una escritura posterior recupera dicha ranura. Como + consecuencia, el número de ranuras usadas que informa + Yac::info no disminuye tras una eliminación, y + Yac::dump sigue mostrando la entrada eliminada + hasta que su ranura se recicla; un valor ttl distinto + de cero situado en el pasado indica una entrada eliminada o caducada, por + lo que, al examinar la salida de Yac::dump, tales + entradas deben ser filtradas por el llamador. + + @@ -27,17 +40,21 @@ keys - - clave string, o array de multiples claves para ser removidas. - + + Una clave de tipo string, o un array de claves + que serán eliminadas. + - ttl + delay - - si se establece un retraso, la eliminación marcará los elementos como inválidos en ttl segundo. - + + Número de segundos antes de que el elemento deje de ser válido. Si se + omite o vale 0, el elemento se invalida de inmediato. + Un valor positivo mantiene el elemento legible durante ese número de + segundos antes de que caduque. + @@ -45,11 +62,65 @@ &reftitle.returnvalues; - + + Devuelve &true; en caso de éxito, o &false; si la clave no estaba presente + en la caché. Dado que una eliminación solo marca la entrada como caducada, + una clave que ha sido eliminada pero aún no sobrescrita se sigue + considerando presente: eliminar de nuevo la misma clave devuelve &true;. + + + Cuando se proporciona un array de claves, se devuelve &true; + únicamente si todas las claves estaban presentes; si falta alguna clave, se + devuelve &false;. + + - + + &reftitle.examples; + + Ejemplo de <methodname>Yac::delete</methodname> + +set("foo", "bar"); + +var_dump($yac->delete("foo")); // bool(true): marcada como caducada +var_dump($yac->get("foo")); // bool(false): a partir de ahora, un fallo +var_dump($yac->delete("foo")); // bool(true) de nuevo: la ranura aún no + // ha sido sobrescrita +var_dump($yac->delete("never")); // bool(false): nunca fue almacenada + +// una eliminación no libera la ranura: slots_used no disminuye, y +// la entrada caducada sigue apareciendo en el volcado +var_dump($yac->info()["slots_used"]); // int(1) +print_r($yac->dump()); // "foo" sigue apareciendo; su ttl + // está en el pasado + +// eliminación retardada: mantiene la entrada legible durante 60 segundos más +$yac->set("tmp", "value"); +var_dump($yac->delete("tmp", 60)); // bool(true) + +// eliminar varias claves a la vez devuelve true solo cuando todas las +// claves estaban presentes +var_dump($yac->delete(array("tmp", "nope"))); // bool(false): falta "nope" +?> +]]> + + + + &reftitle.seealso; + + + Yac::set + Yac::flush + Yac::info + Yac::dump + + + diff --git a/reference/yac/yac/dump.xml b/reference/yac/yac/dump.xml index 6b7d52d0eb..e7667e5e5f 100644 --- a/reference/yac/yac/dump.xml +++ b/reference/yac/yac/dump.xml @@ -1,34 +1,54 @@ - - - + Yac::dump - Volcar cache + Vuelca las entradas de la caché para su inspección &reftitle.description; - public mixedYac::dump - intnum + public arrayYac::dump + intlimit100 + intoffset0 - - Volcar valores almacenados en caché - + + Vuelca los metadatos de las entradas almacenadas actualmente en la caché. + Los valores en sí no son devueltos. + &reftitle.parameters; - num + 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 - - El número máximo de artículos debe ser devuelto - + + 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. + @@ -36,12 +56,221 @@ &reftitle.returnvalues; + + 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, eliminada o expira (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. + + + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::dump</methodname> + +set("foo", "bar"); +$yac->set("baz", "qux"); + +print_r($yac->dump()); +?> +]]> + + &example.outputs.similar; + + 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. + + + + 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. + + +dump($page_size, $page_size * ($page_num - 1)); + +var_dump(count($page)); +?> +]]> + + &example.outputs.similar; + + + + + 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. + + + + + + &reftitle.seealso; - mixed + + Yac::info + - - - + Yac::flush - Limpiar el caché + Vacía la caché @@ -15,9 +13,12 @@ public boolYac::flush - - Eliminar todos los valores almacenados - + + Elimina todos los valores almacenados en caché. Dado que la caché es + compartida por todos los procesos de la misma máquina, esto vacía la + caché de forma global; el prefijo de clave proporcionado a + Yac::__construct no limita lo que se elimina. + @@ -27,12 +28,46 @@ &reftitle.returnvalues; + + Devuelve &true;. + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::flush</methodname> + +set("foo", "bar"); + +$other = new Yac("app2_"); +$other->set("baz", "qux"); + +// flush vacía la caché completa: las entradas de todas las instancias, +// independientemente del prefijo utilizado al almacenarlas +$yac->flush(); + +var_dump($yac->get("foo")); // bool(false) +var_dump($other->get("baz")); // bool(false) +?> +]]> + + + + + + &reftitle.seealso; - bool, siempre true + + Yac::delete + Yac::info + - - - + Yac::get - Recuperar los valores de caché + Recupera valores de la caché &reftitle.description; public mixedYac::get - stringarraykey - intcas&null; + stringarraykeys + mixeddefault&null; - - Recuperar los valores de caché - + + Recupera valores de la caché + &reftitle.parameters; - key + keys - - claves &string;, o &array; de multiples claves. - + + Una clave de tipo string, o un array de claves. + - cas + default - - Si no es &null;, se ajustará al caso del artículo recuperado. - + + El valor que se devuelve cuando la clave (o las claves) solicitada no + está presente en la caché, disponible a partir de yac 2.4.0. Si se + omite, un fallo de caché devuelve &false;. + + + + Antes de yac 2.4.0, esta posición de argumento contenía un token + $cas por referencia en lugar de un valor por + defecto. El código que pasaba ese token o dependía de él debe + actualizarse al migrar a la versión 2.4.0. + + @@ -45,12 +53,65 @@ &reftitle.returnvalues; + + Para una clave de tipo string, devuelve el valor almacenado en + caché si se encuentra, y en caso contrario el valor de + default (o &false; si no se indicó ningún valor por + defecto). + + + Para un array de claves, devuelve un array que contiene los + valores encontrados indexados por sus claves. Las claves que no están + presentes en la caché se omiten del resultado a partir de yac 2.4.0, o se + rellenan con el valor de default si se indicó uno; + antes de la versión 2.4.0, se insertaba un marcador &false; por cada clave + ausente. + + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::get</methodname> + +set("foo", "bar"); +var_dump($yac->get("foo")); // string(3) "bar" +var_dump($yac->get("missing")); // bool(false): un fallo de caché + +// un fallo de caché y un false almacenado son indistinguibles sin un valor +// por defecto; un valor centinela (disponible a partir de yac 2.4.0) permite +// diferenciarlos +$yac->set("flag", false); +var_dump($yac->get("flag")); // bool(false): el valor almacenado +var_dump($yac->get("missing", false)); // bool(false): un fallo de caché, misma forma +var_dump($yac->get("flag", "__NONE__")); // bool(false): el valor almacenado +var_dump($yac->get("missing", "__NONE__")); // string(8) "__NONE__": un fallo de caché + +// con un array de claves, solo las claves encontradas están presentes en el resultado +$yac->set("foo2", "bar2"); +var_dump($yac->get(array("foo", "foo2", "missing"))); +// array(2) { ["foo"]=> string(3) "bar" ["foo2"]=> string(4) "bar2" } +?> +]]> + + + + + + &reftitle.seealso; - mixed en caso de éxito, false en caso de error + + Yac::set + Yac::__get + - - - + Yac::__get - Getter + Recupera un valor usando la sintaxis de propiedades @@ -15,9 +13,11 @@ public mixedYac::__get stringkey - - Recupera los valores del caché - + + Recupera un valor de la caché; se invoca al leer una propiedad de una + instancia de Yac: $yac->foo es + equivalente a $yac->get("foo"). + @@ -26,9 +26,9 @@ key - - clave &string; - + + El nombre de la propiedad, utilizado como clave de la caché. + @@ -36,12 +36,47 @@ &reftitle.returnvalues; + + El valor almacenado en caso de acierto, &null; cuando la clave no está + presente en la caché. + + + + A diferencia de Yac::get, la sintaxis de + propiedades no puede distinguir un &null; almacenado de una clave + ausente, y solo admite claves individuales. + + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::__get</methodname> + +set("foo", "bar"); + +var_dump($yac->foo); // string(3) "bar" +var_dump($yac->missing); // NULL +?> +]]> + + + + + + &reftitle.seealso; - mixed en caso de éxito, &null; en caso de error. + + Yac::get + Yac::__set + - +--> \ No newline at end of file diff --git a/reference/yac/yac/info.xml b/reference/yac/yac/info.xml index 8ea4ff1d95..d61b58b3dd 100644 --- a/reference/yac/yac/info.xml +++ b/reference/yac/yac/info.xml @@ -1,7 +1,5 @@ - - - + @@ -15,9 +13,9 @@ public arrayYac::info - - Obtener el estado del sistema de caché - + + Obtiene el estado del sistema de caché + @@ -27,14 +25,150 @@ &reftitle.returnvalues; + + Devuelve un array con las siguientes claves: + + + + memory_size + + Memoria compartida total en uso, en bytes: la tabla de slots más los + bloques de valores. + + + + slots_memory_size + + Memoria reservada para la tabla de slots hash, en bytes. + + + + values_memory_size + + Memoria reservada para los valores almacenados, en bytes. + + + + segment_size + + Tamaño de un segmento de memoria de valores, en bytes. + + + + segment_num + + Número de segmentos de memoria de valores. + + + + miss + + Número de fallos de caché: búsquedas que no encontraron nada o que + encontraron una entrada expirada. + + + + hits + + Número de aciertos de caché: búsquedas satisfactorias. + + + + fails + + Número de almacenamientos fallidos: almacenamientos que no pudieron + asignar un bloque de valor. + + + + kicks + + Número de expulsiones: cuántas veces hubo que expulsar una entrada + existente porque la ruta de slots candidata estaba llena. + + + + recycles + + Número de veces que el asignador llegó al final de un segmento y + volvió a su comienzo. + + + + start_time + + La marca de tiempo Unix en la que se inicializó el caché en memoria + compartida. + + + + slots_size + + Número total de slots hash. + + + + slots_used + + Número de slots hash ocupados actualmente. + + + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::info</methodname> + +set("foo", "bar"); + +print_r($yac->info()); +?> +]]> + + &example.outputs.similar; + + 46137344 + [slots_memory_size] => 4194304 + [values_memory_size] => 41943040 + [segment_size] => 4194304 + [segment_num] => 10 + [miss] => 0 + [hits] => 0 + [fails] => 0 + [kicks] => 0 + [recycles] => 0 + [start_time] => 1725955200 + [slots_size] => 32768 + [slots_used] => 1 +) +]]> + + + La tasa de aciertos puede calcularse como + hits / (hits + miss); un contador + kicks o fails creciente indica + que el caché está bajo presión de memoria. + + + + + + &reftitle.seealso; - Devuelve un array, consistente con: - "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", - "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used" + + Yac::dump + - - - + Yac::set - Guardar en el caché + Almacena un valor en la caché &reftitle.description; public boolYac::set - stringkeys + stringarraykeys mixedvalue intttl0 - public boolYac::add - arraykey_vals + public boolYac::set + arrayvalues + intttl0 - - Añade un elemento a la caché, si la clave ya existe, se sobreescribe. - + + Almacena un valor en la caché. Si la clave ya existe, la entrada + existente se sobrescribe, independientemente de si ha expirado. + @@ -32,25 +32,30 @@ keys - - clave &string; - + + Una clave de tipo string, o un array de + pares clave => valor que almacenar en una sola llamada. + value - - valor mixed, Todo tipo de valor php podría ser almacenado excepto &resource; - + + El valor que almacenar. Se puede almacenar cualquier tipo de PHP excepto + resource. Solo se utiliza en la forma de clave única; cuando + keys es un array, este argumento es en su lugar el + parámetro opcional ttl. + ttl - - tiempo de expiración - + + Tiempo de vida en segundos. 0 significa que la entrada + nunca expira por tiempo. + @@ -58,8 +63,44 @@ &reftitle.returnvalues; + + Devuelve &true; en caso de éxito, &false; en caso de error. + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::set</methodname> + +set("foo", "bar"); // almacena un único valor +$yac->set("foo", "baz"); // sobrescribe la entrada existente + +// ttl en segundos: la entrada expira transcurridos 5 segundos +$yac->set("short-lived", "value", 5); +sleep(6); +var_dump($yac->get("short-lived")); // bool(false): ha expirado + +// almacena varios pares clave => valor con una sola llamada +$yac->set(array("a" => 1, "b" => 2)); +?> +]]> + + + + + + &reftitle.seealso; - el valor de sí mismo + + Yac::add + Yac::get + Yac::__set + diff --git a/reference/yac/yac/setter.xml b/reference/yac/yac/setter.xml index bb08cad8de..7346b6fb80 100644 --- a/reference/yac/yac/setter.xml +++ b/reference/yac/yac/setter.xml @@ -1,43 +1,45 @@ - - - + Yac::__set - Setter + Almacena un valor utilizando la sintaxis de propiedades &reftitle.description; public mixedYac::__set - stringkeys + stringkey mixedvalue - - almacena un elemento en el caché - + + Almacena un valor en la caché; se invoca al escribir una propiedad de una + instancia de Yac: $yac->foo = "bar" + es equivalente a $yac->set("foo", "bar"), sin + ttl. + &reftitle.parameters; - keys + key - - clave &string; - + + El nombre de la propiedad, utilizado como clave de la caché. + value - - valor mixed, Todo tipo de valor php podría ser almacenado excepto &resource; - + + El valor a almacenar. Se puede almacenar cualquier tipo de PHP excepto + resource. + @@ -45,8 +47,35 @@ &reftitle.returnvalues; + + Devuelve el valor almacenado. + + + + + &reftitle.examples; + + Ejemplo de <methodname>Yac::__set</methodname> + +foo = "bar"; // almacenado sin ttl +var_dump($yac->get("foo")); // string(3) "bar" +?> +]]> + + + + + + &reftitle.seealso; - Siempre devuelve el valor de sí mismo + + Yac::set + Yac::__get +