Harbour Runtime Binary (HRB)

Referencia técnica de módulos Harbour compilados y carga dinámica

Estado Versión inicial de investigación
Tecnología / Formato Harbour · HRB (p-code)
Fuente Principal Harbour Core
Objetivo Compilación, carga y ciclo de vida

01 Introducción

Harbour dispone de un mecanismo para compilar código fuente Harbour en módulos binarios que pueden cargarse durante la ejecución de una aplicación. Estos módulos se conocen como HRB (Harbour Runtime Binary).

Un módulo HRB contiene p-code Harbour y la información necesaria para que la máquina virtual de Harbour pueda interpretar y ejecutar ese código. La característica fundamental es que permite incorporar funcionalidades a una aplicación sin tener que compilar y enlazar nuevamente todo el ejecutable principal.

Casos de uso principales:

1.1. HRB no es una DLL

Es importante distinguir técnicamente ambos mecanismos de extensión:

Módulo HRB Biblioteca DLL Nativa
Contiene p-code Harbour Contiene código máquina nativo
Se ejecuta mediante la VM Harbour Se ejecuta directamente mediante el Sistema Operativo
Utiliza el runtime Harbour Utiliza ABI y convenciones de llamada nativas
Puede utilizar símbolos Harbour directamente Expone funciones nativas exportadas
Se carga mediante la API HRB (hb_hrbLoad) Se carga mediante mecanismos del SO (LoadLibrary)
Dependencia de entorno

Un HRB no es un ejecutable independiente: necesita obligatoriamente un entorno Harbour (VM) compatible activo para poder cargarse y ejecutarse.

02 Arquitectura general

La aplicación principal conserva su entorno de ejecución intacto, mientras que el módulo HRB incorpora código p-code adicional que se integra dinámicamente con la máquina virtual.

Aplicación Principal Host Executable Harbour VM Tabla Símbolos / Pila HRB Loader hb_hrbLoad() Módulo HRB Archivo .hrb / .hbr Código p-code Ejecución en VM
Flujo de carga e integración del código p-code dentro de la Máquina Virtual Harbour.

2.1. Máquina virtual Harbour

La VM es el componente encargado de ejecutar las instrucciones p-code. Su funcionamiento involucra:

El documento oficial doc/vm.txt describe en detalle estos subsistemas: github.com/harbour/core/blob/master/doc/vm.txt.

03 API de administración HRB

Harbour proporciona un conjunto de funciones integradas en su espacio de nombres público para administrar módulos HRB:

Función Responsabilidad principal
hb_hrbLoad() Carga un módulo HRB en memoria y devuelve su handle/referencia.
hb_hrbRun() Carga y ejecuta un módulo de forma directa sin gestión manual del ciclo.
hb_hrbDo() Ejecuta código de un módulo previamente cargado con hb_hrbLoad().
hb_hrbUnload() Libera y descarga un módulo HRB de la memoria.
hb_hrbGetFunList() Obtiene la lista de funciones exportadas/contenidas en el módulo.
hb_hrbGetFunSym() Busca y devuelve el símbolo correspondiente a una función específica.
hb_hrbSignature() Obtiene la firma identificadora del formato binario HRB.

3.1. hb_hrbLoad()

Permite cargar un archivo HRB en memoria y devuelve una referencia utilizable para ejecuciones posteriores. Admite opciones de vinculación y parámetros destinados al procedimiento de inicialización del módulo.

Harbour — Sintaxis y uso básico
// Esquema general documentado
pHRB := hb_hrbLoad( [nOptions], cHrbFileName, [xParameters...] )

// Ejemplo básico
pHRB := hb_hrbLoad( "plugin.hrb" )

Nota: Los parámetros exactos y constantes de opciones deben verificarse contra hbhrb.ch de la versión Harbour utilizada.

3.2. hb_hrbRun()

Ejecuta un módulo HRB directamente. Es útil cuando se desea correr un script compilado sin administrar explícitamente su ciclo de carga y descarga. La ejecución ocurre dentro del mismo entorno Harbour que realiza la llamada (no es IPC).

Harbour
xResult := hb_hrbRun( "plugin.hrb" )

3.3. hb_hrbDo()

Permite ejecutar código de un módulo que ya fue cargado previamente mediante hb_hrbLoad().

Harbour
pHRB := hb_hrbLoad( "plugin.hrb" )

IF pHRB != NIL
   hb_hrbDo( pHRB )
ENDIF

3.4. hb_hrbUnload()

Libera el código HRB previamente cargado en memoria:

Harbour
hb_hrbUnload( pHRB )
Operación delicada

Antes de descargar un módulo deben liberarse todas las referencias activas (objetos, codeblocks, punteros a símbolos) que dependan de su código.

3.5. hb_hrbGetFunList()

Permite obtener información sobre las funciones presentes en un módulo HRB cargado. Resulta fundamental para implementar mecanismos de introspección y descubrimiento automático de funcionalidades en sistemas de plugins.

3.6. hb_hrbGetFunSym()

Busca un símbolo correspondiente a una función dentro de un módulo HRB. Si el símbolo existe, puede utilizarse para invocar la función mediante los mecanismos de evaluación de símbolos de Harbour (como hb_ExecFromArray() o Eval()).

3.7. hb_hrbSignature()

Devuelve la firma identificadora del formato binario HRB. Es útil para validar compatibilidad de versión del formato, pero no debe confundirse con una firma criptográfica de integridad o autenticidad.

04 Opciones de vinculación

La carga de módulos HRB admite diferentes modos de vinculación definidos mediante constantes HB_HRB_BIND_* en el archivo de cabecera include/hbhrb.ch.

Estas opciones determinan cómo se resuelven y enlazan los símbolos entre el módulo cargado y la tabla de símbolos de la aplicación anfitriona:

Pendiente de verificación

No establecer valores numéricos fijos ni asumir el comportamiento de cada modalidad sin inspeccionar el archivo include/hbhrb.ch correspondiente a la versión exacta de Harbour compilada en el entorno.

05 Comunicación entre aplicación y módulo

A diferencia de procesos externos, HRB no utiliza IPC, sockets ni pipes para comunicarse con su aplicación anfitriona: ambos ejecutan código dentro de la misma Máquina Virtual Harbour.

La comunicación puede realizarse de forma nativa mediante parámetros de funciones, valores de retorno, símbolos públicos, objetos, arrays, hashes y codeblocks.

Mecanismo Tipos de datos soportados Observaciones
Parámetros de entrada Strings, números, fechas, lógicos, arrays, hashes, objetos Pueden pasarse tanto en la inicialización (hb_hrbLoad) como en llamadas posteriores. Historial documentado en doc/oldnews.txt.
Valores de retorno String, Número, Fecha, Logical, Array, Hash, Objeto, NIL Se recomienda validar la compatibilidad concreta de objetos complejos mediante pruebas ejecutables.

06 Funciones, símbolos y clases

Los módulos HRB interactúan directamente con el sistema de símbolos de Harbour, permitiendo que la aplicación anfitriona localice funciones y ejecute código del módulo.

Respecto a la Programación Orientada a Objetos, deben investigarse y validarse los siguientes puntos críticos cuando se definen clases dentro de módulos dinámicos:

  1. Registro de clases en la tabla global de clases de la VM.
  2. Resolución de métodos e herencia con clases del anfitrión.
  3. Instanciación de objetos desde el host hacia clases definidas en el HRB.
  4. Referencias cruzadas a clases definidas en otros módulos HRB.
  5. Descarga de módulos que contienen clases registradas activas.
  6. Estado de referencias a métodos u objetos existentes tras descargar el módulo.
Advertencia sobre instancias

No debe asumirse que invocar hb_hrbUnload() elimina o invalida de forma segura todos los objetos que fueron instanciados a partir de clases definidas en ese módulo.

07 Variables y estado

Un módulo HRB mantiene su propio estado de ejecución. Es necesario distinguir el alcance de cada tipo de variable:

Debe estudiarse particularmente qué ocurre cuando un mismo módulo HRB se carga múltiples veces o cuando conviven varios módulos que declaran símbolos con nombres coincidentes.

08 Ciclo de vida de un módulo

Un ciclo de vida controlado para un plugin HRB sigue esta secuencia estricta:

hb_hrbLoad() Carga en VM Obtener Símbolos GetFunList/Sym Ejecutar hb_hrbDo / Eval Liberar Refs Objetos / Blocks hb_hrbUnload() Descarga segura
Recomendación de arquitectura: Administrador de Plugins

Implementar un gestor centralizado que controle: módulos cargados, identificadores únicos, funciones registradas, objetos instanciados, dependencias, contador de referencias activas y estados de inicialización/descarga. Nunca descargar un módulo mientras existan referencias activas dependientes de él.

09 Seguridad

HRB no debe considerarse un formato seguro ni aislado (sandbox) por el simple hecho de ser binario. Un módulo HRB contiene p-code ejecutable con los mismos privilegios y permisos del sistema operativo que la aplicación anfitriona.

10 Diferencia entre HRB y proveedores de Workspace

Workspace utiliza archivos con extensión .hbr ubicados en el directorio:

Ruta de proveedores en Workspace
E:\WorkSpacein\Plugins\Providers

Archivos identificados actualmente:

bcc.hbr fpc.hbr gcc.hbr hbmk2.hbr msvc.hbr pelles.hbr

Aunque la extensión .hbr difiere de la extensión convencional .hrb de Harbour Runtime Binary, la inspección de estos archivos revela estructuras de módulos Harbour compilados. Por lo tanto:

La relación exacta entre esta extensión y el cargador utilizado debe verificarse en el código fuente de Workspace.

11 Fuentes oficiales y referencias

Recurso Ubicación / Enlace Propósito
Harbour Core github.com/harbour/core Repositorio principal del proyecto
Máquina Virtual doc/vm.txt Arquitectura y subsistemas de la VM
Funciones HRB include/harbour.hbx Declaraciones de símbolos públicos HRB
Opciones HRB include/hbhrb.ch Constantes de vinculación HB_HRB_BIND_*
Historial doc/oldnews.txt Evolución de la API y soporte de parámetros no string

12 Plan de verificación experimental

Para validar cada comportamiento en la versión exacta de Harbour utilizada, se propone construir una aplicación anfitriona mínima y ejecutar la siguiente batería de pruebas:

Prueba 1: Cargahb_hrbLoad
  • Generar un archivo HRB de prueba.
  • Cargar con hb_hrbLoad().
  • Comprobar handle devuelto y registrar errores.
Prueba 2: Ejecuciónhb_hrbDo
  • Ejecutar función principal del módulo.
  • Verificar recepción de parámetros.
  • Comprobar valor de retorno.
Prueba 3: ComunicaciónTipos
  • Probar intercambio de String, Número y Logical.
  • Probar estructuras complejas: Array, Hash y Objeto.
Prueba 4: SímbolosIntrospección
  • Enumerar funciones con hb_hrbGetFunList().
  • Buscar símbolos con hb_hrbGetFunSym().
  • Invocar funciones específicas dinámicamente.
Prueba 5: EstadoPersistencia
  • Modificar variables STATIC internas.
  • Invocar funciones repetidamente.
  • Observar persistencia entre llamadas.
Prueba 6: Descargahb_hrbUnload
  • Liberar referencias activas del módulo.
  • Ejecutar hb_hrbUnload().
  • Verificar liberación limpia en memoria.
Prueba 7: VinculaciónBIND_*
  • Probar distintas banderas HB_HRB_BIND_*.
  • Observar resolución y colisión de símbolos.

13 Conclusión

HRB proporciona a Harbour un mecanismo de extensibilidad dinámica potente y ligero basado en p-code compilado, permitiendo incorporar funcionalidades en tiempo de ejecución sin depender de DLLs nativas ni recompilar el ejecutable principal.

Para implementarlo de forma robusta en producción es indispensable dominar la estructura del módulo, las reglas de vinculación de símbolos, el intercambio de datos y, especialmente, el ciclo de vida y control de referencias previo a la descarga.