# threads.dkh: hilos, candados y caché en memoria `threads.dkh` ejecuta programas DKL en paralelo, espera sus resultados, ofrece candados con nombre para que dos peticiones no hagan lo mismo a la vez y guarda datos en una memoria del proceso con caducidad. Viene con la distribución de Devkron 2.0 (`Devkron.Ext.Threads.dll`) y sustituye a `dkl.async`. ## Cuándo usarla - **Trabajo por lotes**: procesar 1 000 facturas, timbres o correos repartiéndolos entre los núcleos del servidor (`threads.pool`). - **Varias consultas lentas a la vez**: lanzar tres consultas y esperar a todas o a la primera. - **Folios y consecutivos en FastCGI**, donde un mismo proceso atiende muchas peticiones simultáneas: `threads.lock` evita que dos peticiones tomen el mismo número. - **Caché de datos que cambian poco** (catálogos, configuración, tokens de acceso) para no ir a la base de datos o al proveedor en cada petición. ```dkl #include "threads.dkh" ``` ## Cómo funciona un hilo Cada hilo es una **ejecución aislada**, como si se lanzara `dkl` aparte: - Tiene sus propias variables globales, funciones, rutas de `#path`, conexiones y objetos (se liberan al terminar el hilo). No ve nada del programa que lo lanzó, así que el programa del hilo hace sus propios `#include`. - **Entrada**: el dato llega en la global `@`, con el nombre que usted indique. Un registro o lista se pasa tal cual (el hilo y el padre comparten **el mismo objeto**: no lo modifiquen los dos a la vez). Una cadena o un número llega envuelto en un registro `{value: …}`: léalo con `field.num(@var, "value")` o `field.str(@var, "value")`. - **Salida**: lo que devuelve `threads.result` es el **texto que produce el contexto declarativo** del programa del hilo (el XML de su árbol, como `runscript`). Lo que el hilo escribe con `print` **no** se devuelve: va directo a la consola del proceso. - **Errores**: si el programa falla, `threads.error` devuelve el mensaje con el formato `{código} mensaje[Ln= n]`; el hilo no detiene al programa principal. ## Funciones de hilos | Función | Devuelve | Descripción | |---|---|---| | `threads.run(archivo, var, valor)` | tarea | Ejecuta un programa `.dkl` (ruta relativa a la carpeta de trabajo) en un hilo aislado | | `threads.run_code(codigo, var, valor)` | tarea | Igual, con el código DKL en una cadena | | `threads.wait(tareas, ms)` | lógico | `@true` si todas terminaron antes de `ms` milisegundos; `-1` = sin límite. Acepta una tarea o una lista | | `threads.wait_any(tareas, ms)` | número | Índice de la primera que terminó; `-1` si venció el tiempo | | `threads.done(tarea)` | lógico | `@true` si ya terminó (no espera) | | `threads.result(tarea)` | cadena | Salida declarativa del programa; espera a que termine | | `threads.error(tarea)` | cadena | Mensaje de error; `""` si no falló; espera a que termine | | `threads.pool(archivo, var, valores, n)` | lista | Ejecuta el programa una vez por cada elemento de `valores`, máximo `n` a la vez; devuelve las salidas en el orden de los valores. Si alguno falla, lanza error con el primero que falló | | `threads.sleep(ms)` | — | Pausa el hilo actual | | `threads.cpus()` | número | Procesadores lógicos del equipo, para dimensionar `n` | Las tareas se guardan con `ref`: `ref t = threads.run(...)`. ## Ejemplo: procesar 1 000 registros con threads.pool `procesar-factura.dkl` recibe el folio y devuelve el resultado en su árbol declarativo: ```dkl #include "dkli.dkh" #! program "procesar factura" { #include "functions.dkh" #include "threads.dkh" // El valor llega en la global @folio; un número o una cadena llega como {value: ...} folio = field.num(@folio, "value") // Aquí iría el trabajo real: consultar la base, timbrar, enviar el correo... do threads.sleep(5) estado = "ok" if folio == 500 { estado = "rechazada" } #$ factura(folio="#") { $"#" } } ``` `lote.dkl` reparte los 1 000 folios entre los núcleos disponibles: ```dkl #include "dkli.dkh" #! program "lote" { #include "functions.dkh" #include "threads.dkh" ref folios = list.create() for i=1; i<=1000 { do list.addnum(folios, i) } n = threads.cpus() * 2 ref salidas = threads.pool("procesar-factura.dkl", "folio", folios, n) correctos = 0 for i=0; iok<") >= 0 { correctos = correctos + 1 } } do print("Procesados: " + str(list.count(salidas)) + " correctos: " + str(correctos)) do print("Salida del folio 500: " + list.str(salidas, 499)) } ``` Salida (en un equipo de 2 núcleos tarda unos 4 segundos): ``` Procesados: 1000 correctos: 999 Salida del folio 500: rechazada ``` **Cómo elegir `n`**: para trabajo que espera a la red o a la base de datos, de 2 a 4 veces `threads.cpus()`; para cálculo puro, `threads.cpus()`. Más hilos solo consumen memoria. Si un elemento puede fallar sin que deba detenerse el lote, atrape el error dentro del programa del hilo y devuélvalo en su salida: `threads.pool` lanza error ante el primer fallo. ## Ejemplo: varias consultas a la vez `consulta.dkl` simula una consulta lenta; la de inventario falla: ```dkl #include "dkli.dkh" #! program "consulta" { #include "functions.dkh" #include "threads.dkh" // @p llega como registro: {servicio, espera} servicio = field.str(@p, "servicio") do threads.sleep(field.num(@p, "espera")) if servicio == "inventario" { do rise_error(7, "el servicio de inventario no respondió") } #$ respuesta { $"#: listo" } } ``` ```dkl #include "dkli.dkh" #! program "varias consultas" { #include "functions.dkh" #include "threads.dkh" ref tareas = list.create() ref nombres = list.of("tipo-de-cambio", "inventario", "precios") for i=0; i tipo-de-cambio: listo Falló: {7} el servicio de inventario no respondió[Ln= 10] precios: listo ``` ## Ejemplo: código en una cadena y print del hilo ```dkl #include "dkli.dkh" #! program "run_code" { #include "functions.dkh" #include "threads.dkh" codigo = "#include \"dkli.dkh\"\n#!\nprogram \"h\"\n{\n #include \"functions.dkh\"\n x = field.num(@n, \"value\") * 2\n do print(\"esto va a la consola\")\n #$\n doble { $\"#\" }\n}" ref t = threads.run_code(codigo, "n", 21) do print("terminó: " + str(threads.wait(t, -1)) + " " + str(threads.done(t))) do print("resultado: " + threads.result(t)) } ``` Salida: el `print` del hilo sale en la consola y no forma parte del resultado. ``` esto va a la consola terminó: 1 1 resultado: 42 ``` ## Candados | Función | Devuelve | Descripción | |---|---|---| | `threads.lock(nombre, ms)` | lógico | Toma el candado `nombre`; espera hasta `ms` (`0` = no esperar, `-1` = sin límite); `@true` si lo obtuvo | | `threads.unlock(nombre)` | — | Libera el candado; error si no estaba tomado | ## Ejemplo: folio sin duplicados ```dkl #include "dkli.dkh" #! program "folio" { #include "functions.dkh" #include "threads.dkh" // Se llama con el candado tomado; lo libera siempre, también si hay error _folio:: { // En un sistema real: select max(folio)+1 ... e insert, con dbr.* n = cache.num("folio-ventas") + 1 do cache.setnum("folio-ventas", n, 0) do threads.unlock("folio-ventas") return n exception { do threads.unlock("folio-ventas") do rise_error(last_error_code(), last_error()) } } siguiente:: { if not(threads.lock("folio-ventas", 3000)) { do rise_error(1, "El servidor está ocupado, intente de nuevo") } return _folio() } do print("Folio: " + str(siguiente())) do print("Folio: " + str(siguiente())) do print("Candado libre: " + str(threads.lock("folio-ventas", 0))) do threads.unlock("folio-ventas") } ``` Salida: ``` Folio: 1 Folio: 2 Candado libre: 1 ``` Libere siempre el candado, también cuando hay error. Un candado que no se libera bloquea a las siguientes peticiones de ese proceso hasta que se reinicie el servidor. ## Caché del proceso: cache.* | Función | Devuelve | Descripción | |---|---|---| | `cache.set(llave, valor, segundos)` | — | Guarda una cadena, un registro o una lista; `segundos` = vida (`0` = sin caducidad) | | `cache.setnum(llave, numero, segundos)` | — | Guarda un número (use esta para números) | | `cache.get(llave)` | valor | Cadena, número o **copia** del objeto; nulo si no existe o caducó | | `cache.dget(llave, predeterminado)` | valor | Igual, o el predeterminado | | `cache.str(llave)` / `cache.num(llave)` / `cache.obj(llave)` | valor | El valor con ese tipo (`""`, `0` o nulo si no hay) | | `cache.has(llave)` | lógico | `@true` si existe y no ha caducado | | `cache.type(llave)` | número | 0 no existe, 1 cadena, 2 número, 3 objeto | | `cache.del(llave)` | lógico | `@true` si existía | | `cache.clear()` | — | Borra todo el caché del proceso | | `cache.count()` | número | Entradas vigentes | - `cache.set` guarda una **copia serializada** (JSON) del objeto y cada lectura devuelve una copia nueva: modificar lo obtenido no cambia lo guardado, dos peticiones en paralelo nunca comparten el objeto y el fin de una petición no lo libera. Solo se guardan datos que admite `to.json`, no conexiones ni objetos .NET (error `cache.set: el valor no se puede guardar como JSON`). - **Para números use `cache.setnum`**: en DKL un número y una referencia llegan igual a una función y `cache.set` no puede distinguirlos. - Una llave vacía da error (`cache.set: la llave está vacía`). ## Ejemplo: caché de un catálogo ```dkl #include "dkli.dkh" #! program "cache" { #include "functions.dkh" #include "serialize.dkh" #include "threads.dkh" categorias:: { if cache.has("catalogo/categorias") { return cache.obj("catalogo/categorias") } // En un sistema real: ref l = dbr.list(db, "select id, nombre from categorias", @null) ref l = list.create() new c1 { @"id": 1 @"nombre": "Herramientas" } do list.add(l, c1) do cache.set("catalogo/categorias", l, 600) do print("(leído de la base)") return l } ref a = categorias() ref b = categorias() do print(to.json(b) + " entradas: " + str(cache.count())) // Lo que devuelve el caché es una copia: modificarla no cambia lo guardado ref c = list.obj(b, 0) c<"nombre">: "Otra" do print(to.json(cache.obj("catalogo/categorias"))) do cache.setnum("visitas", 41, 0) do cache.setnum("visitas", cache.num("visitas") + 1, 0) do print("visitas: " + str(cache.get("visitas")) + " tipo: " + str(cache.type("visitas"))) do print(cache.dget("no-existe", "predeterminado") + " borrado: " + str(cache.del("visitas"))) } ``` Salida: ``` (leído de la base) [{"id":1,"nombre":"Herramientas"}] entradas: 1 [{"id":1,"nombre":"Herramientas"}] visitas: 42 tipo: 2 predeterminado borrado: 1 ``` ## Errores | Mensaje | Causa | |---|---| | `threads: no se indicó el archivo del programa` | `archivo` vacío | | `threads.run_code: el código es nulo` | `codigo` nulo | | `threads.wait: se esperaba una tarea o una lista de tareas` / `… la lista contiene un elemento que no es una tarea de threads.run` | Argumento equivocado | | `threads.result: se esperaba una tarea de threads.run` | Lo mismo en `result`, `error` o `done` | | `threads.pool: los valores deben ser una lista` | `valores` no es lista | | `threads.pool: falló el elemento N: {código} mensaje[Ln= n]` | Falló la ejecución número N (desde 0) | | `threads.lock: el nombre del candado está vacío` | Nombre vacío | | `threads.unlock: el candado '…' no está tomado` | Se liberó dos veces o nunca se tomó | ## Advertencias - **El caché y los candados son por proceso** y se comparten entre todo lo que corre en ese proceso: en un servidor FastCGI que atiende varios sitios, **los sitios comparten el mismo caché y los mismos candados**. Ponga a las llaves y a los nombres de candado un prefijo propio del sitio o de la aplicación (`"ventas.ejemplo.com/folio"`). - Con varios procesos FastCGI (varios puertos tras nginx) o varios servidores, cada proceso tiene su caché y sus candados. Para folios entre procesos use además `dbr.lock` o una restricción única en la base de datos. - **El caché se pierde al reiniciar** `dkl -fastcgi`. No guarde ahí nada que no pueda volver a obtener. En consola dura lo que dura el programa. - Los hilos no comparten conexiones ni variables: cada uno abre las suyas y hace sus `#include`. - Un equipo con pocos núcleos compartido con MySQL y nginx no gana nada con muchos hilos de cálculo; mida con un lote pequeño.