hwlocality_shmem(3)

okay bestie, welcome to hwlocality_shmem(3) — the Library Functions Manual page about sharing topologies between processes, and it's literally giving main character energy for multi-process setups. 🫶✨ No cap, this page is a whole vibe, so let's get into it.

🌸 NAME 🌸

hwlocality_shmem — Sharing topologies between processes 💖

✨ SYNOPSIS ✨

🎀 Functions 🎀

bestie, here are the three functions, exactly as written:

int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t
           *lengthp, unsigned long flags)
int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd,
           hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
           unsigned long flags)
int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd,
           hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
           unsigned long flags)

🦋 Detailed Description 🦋

Okay so the whole point: these functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer. That's the headline, and the rest is the recipe:

• The master process must first get the required shared-memory size for storing this topology with hwloc_shmem_topology_get_length(). 📏
• Then it must find a virtual memory area of that size that is available in all processes (identical virtual addresses in all processes). On Linux, this can be done by comparing holes found in /proc/<pid>/maps for each process. 🗺️
• Once found, it must open a destination file for storing the buffer, and pass it to hwloc_shmem_topology_write() together with virtual memory address and length obtained above. 📝
• Other processes may then adopt this shared topology by opening the same file and passing it to hwloc_shmem_topology_adopt() with the exact same virtual memory address and length. 🫶

👑 Function Documentation 👑

💅 hwloc_shmem_topology_adopt 💅

int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd,
           hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
           unsigned long flags)

Adopt a shared memory topology stored in a file. Map a file in virtual memory and adopt the topology that was previously stored there with hwloc_shmem_topology_write(). It's giving “come join the shared-memory party.” 🎉

The returned adopted topology in topologyp can be used just like any topology. And it must be destroyed with hwloc_topology_destroy() as usual. 🫶

However the topology is read-only. For instance, it cannot be modified with hwloc_topology_restrict() and object userdata pointers cannot be changed. So no sneaky edits, bestie — strictly look-but-don't-touch energy. 🙈

The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be mapped at virtual address mmap_address.

The file pointed by descriptor fd, the offset fileoffset, the requested mapping virtual address mmap_address and the length length must be identical to what was given to hwloc_shmem_topology_write() earlier. No cap, identical means identical. ✨

Note: Flags flags are currently unused, must be 0. 💅 The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory. 🧚 This function takes care of calling hwloc_topology_abi_check(). 🔍

Returns: 💖

• 0 on success.
• -1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
• -1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned, or do not match what was given to hwloc_shmem_topology_write() earlier.
• -1 with errno set to EINVAL if the layout of the topology structure is different between the writer process and the adopter process.

🌸 hwloc_shmem_topology_get_length 🌸

int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t
           *lengthp, unsigned long flags)

Get the required shared memory length for storing a topology. This length (in bytes) must be used in hwloc_shmem_topology_write() and hwloc_shmem_topology_adopt() later. So yes, it's the little measuring-tape function. 📏✨

Returns: the length, or -1 on error, for instance if flags are invalid.

Note: Flags flags are currently unused, must be 0. 🎀

🦋 hwloc_shmem_topology_write 🦋

int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd,
           hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
           unsigned long flags)

Duplicate a topology to a shared memory file. Temporarily map a file in virtual memory and duplicate the topology topology by allocating duplicates in there. It's giving “copy-paste but make it shared memory.” 💅

The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be temporarily mapped at virtual address mmap_address during the duplication.

The mapping length length must have been previously obtained with hwloc_shmem_topology_get_length() and the topology must not have been modified in the meantime. No cap — that's the rule. 🫶

Note: Flags flags are currently unused, must be 0. ✨ The object userdata pointer is duplicated but the pointed buffer is not. However the caller may also allocate it manually in shared memory to share it as well. 🧚

Returns: 💖

• 0 on success.
• -1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
• -1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned.

🎀 Author 🎀

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code. ngl, Doxygen did the typing and I'm just here to make it cute. 💻💖

---

P.S. this page signs off from Hardware Locality (hwloc), Version 2.15.0, and the manual is hwlocality_shmem(3) — the footer has no date, so I'm not inventing one, periodt. Mwah 💋✨