Dark-Horse-Linux/dpm-core-ng
3
0
Fork 0
Code Issues Pull Requests Actions Activity

Describe dpm_module_execute as the entry point, not the whole surface

Browse Source 
A module's reported version is consumed: a calling module reads it
through dpm_module_info_of and decides from it whether to issue a
command. Calling dpm_module_execute the module's entire functional
surface contradicted that.

dpm_module_execute is the only entry through which a module performs
work. dpm_module_version and dpm_module_description are what it reports
about itself, read at load and served to consumers, and the contract
page in the public header now says so.
This commit is contained in:
Chris Punches
2026-08-15 20:51:44 -04:00
parent 99173d27ea
commit cafdeefa11
3 changed files with 16 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
include/dpm/core.h
View File

@@ -351,10 +351,16 @@ DPM_API const char* dpm_last_error(dpm_ctx* ctx);
*
* @section module_contract_surface The Functional Surface
*
* dpm_module_execute is the module's entire functional surface; its
* capabilities are addressed by command string, so a module publishes
* no headers, struct layouts, or symbols to anything that calls it.
* NULL or an empty command behaves as the module's help command.
* dpm_module_execute is the only entry through which a module performs
* work; its capabilities are addressed by command string, so a module
* publishes no headers, struct layouts, or symbols to anything that
* calls it. NULL or an empty command behaves as the module's help
* command.
*
* dpm_module_version and dpm_module_description are what a module
* reports about itself. The library reads both at load and serves them
* to consumers through dpm_module_info_of, where the version is what a
* calling module judges before deciding to issue a command.
*
* @section module_contract_version Version Compatibility
*
@@ -364,6 +370,10 @@ DPM_API const char* dpm_last_error(dpm_ctx* ctx);
* module is built against the system-installed libdpm-core.so and is
* responsible for being correct against it.
*
* The same holds toward a peer. A module requires the peer by name,
* reads the version the library reports, and decides whether that
* version suits the commands it intends to issue.
*
* @section module_contract_validation Validation
*
* The library refuses to load any module that does not validate