Skip to content

hwloc ABI for applications, plugins and shmem

Jump to bottom
Brice Goglin edited this page Nov 22, 2018 · 1 revision

There are 4 different kinds of structure privacy in hwloc:

  1. The main hwloc_obj structure and related attributes are public, anybody can consult them
  2. The core of the topology (where the tree and levels are stored) that is used at runtime (between load and destroy) is private to application, except when doing shmem_write/adopt() (another process will need to understand it). That part doesn't change often.
  3. The temporary part of the topology (where temporary things are stored during discovery), it's totally private to libhwloc, dynamically-loaded plugins cannot access it. That part changes quite often.
  4. Plugin and component structures (in hwloc/plugins.h) are accessible to plugins

Hence, 4 kinds of users a) Application only access (1), it's protected by libhwloc soname. b) Dynamically-loaded plugins access (4) (and possibly (1)), it's protected by HWLOC_COMPONENT_ABI (checked when loading a plugin) c) shmem_write/adopt() access (2) and (1), it's protected by HWLOC_TOPOLOGY_ABI (in private/private.h, checked when adopting a topology) d) Internal

(a) and (b) are actually very similar. The plugin API is available to applications in practice, but most of it may only be used during discovery anyway. The libhwloc soname protects external users against changes in the main application ABI and in the plugin/component ABI. HWLOC_COMPONENT_ABI protects libhwloc against plugins built for an older ABI.

One could consider using HWLOC_TOPOLOGY_ABI instead of HWLOC_COMPONENT_ABI. But plugins require the entire topology structure to be unchanged (2+3), while shmem only require (2). Restricting changes to (3) would be annoying for internal improvement of the discovery.

Clone this wiki locally