HoloOcean Client

The client used for subscribing shared memory between python and c++.

Classes:

HoloOceanClient([uuid])

HoloOceanClient for controlling a shared memory session.

class holoocean.holooceanclient.HoloOceanClient(uuid='')

HoloOceanClient for controlling a shared memory session.

Parameters:: uuid (str, optional) – A UUID to indicate which server this client is associated with. The same UUID should be passed to the world through a command line flag. Defaults to “”.

Methods:

`acquire`([timeout])	Used to acquire control.
`malloc`(key, shape, dtype)	Allocates a block of shared memory, and returns a numpy array whose data corresponds with that block.
`release`()	Used to release control.

acquire(timeout=60): Used to acquire control. Will wait until the HolodeckServer has finished its work.

malloc(key, shape, dtype)

Allocates a block of shared memory, and returns a numpy array whose data corresponds with that block.

NOTE: key should never be reused for a buffer of a different size/dtype while the previous one is still in use. Both this client and the engine independently shm_open / ftruncate / mmap the same named object; reusing a key at a different size resizes that object in place, and there’s no synchronization to guarantee the other side has stopped using the old-sized mapping first – whichever side touches it during the resize can SIGBUS. Agent.add_sensors() avoids this by giving a sensor a fresh, never-before-used engine-facing name whenever the buffer shape/dtype it requests changes, and only reusing its previous name when the shape/dtype is unchanged – so key here is never reused across an actual size change in practice, and this function itself needs no change to stay safe. Reuse-when-unchanged also keeps memory bounded: nothing on either side frees a buffer once allocated (see total_bytes_allocated above, and UHolodeckServer::Free() on the engine side, which frees the engine’s own copy on RemoveSensorCommand but has no client-side equivalent – this client’s copy of a buffer isn’t released until the whole process exits), so a key that’s actually new every time would leak a full buffer’s worth of memory on every single sensor add.

Parameters:

key (str) – The key to identify the block.
shape (list of int) – The shape of the numpy array to allocate.
dtype (type) – The numpy data type (e.g. np.float32).

Returns:

The numpy array that is positioned on the shared memory.

Return type:

np.ndarray

release(): Used to release control. Will allow the HolodeckServer to take a step.