How to name a box¶

A second process finds a box by its name, so every box needs one. You can let the class pick the name for you, give the class a fixed name, or name each box when you create it. Pick the first unless one of the others fits better: it needs no setup and works in every process that imports the class.

Let the class name the box¶

When you call the class, it creates a box under a name it works out itself, and attach with no name opens that same box:

from sharedbox import SegmentExistsError, SharedBox


class Motor(SharedBox, identity="example-motor"):
    position: int = 0


motor = Motor()
same = Motor.attach()
print(same.name == motor.name)  # True

The name comes from the class's identity: normally where the class is defined, module.qualname, or the identity keyword if the class sets one, as Motor does here. Every process that imports the class works out the same name, so you never have to pass it around.

Set identity when you might move the class to another module or rename it. With identity set, moving or renaming the class doesn't change its identity, so the box keeps its name and running processes still find it.

Give the class a fixed name¶

If you'd rather see a name you recognise, set the name keyword on the class:

class Settings(SharedBox, name="example-settings"):
    rate: float = 20.0


settings = Settings()
print(settings.name)  # example-settings

A readable name is easier to spot, for example when you list /dev/shm on Linux to see which boxes exist. SharedBox lists the characters a name may use.

Name each box when you create it¶

When you need several boxes of the same class, say one per motor, give each its own name when you create it with create, and pass the same name to attach:

x_axis = Motor.create("example-x-axis")
y_axis = Motor.create("example-y-axis", 5)
y_view = Motor.attach("example-y-axis")
print(y_view.position)  # 5

After the name, create takes the field values just like calling the class does.

If the name is taken¶

You can't create a box under a name that is already in use; you get SegmentExistsError instead:

try:
    Motor.create("example-x-axis")
except SegmentExistsError as error:
    print(error)  # a segment named 'example-x-axis' already exists; its creator, ...

The message tells you why the name is taken: either the process that created it is still running, or, on Linux, the box was left behind by a process that crashed. Pick another name, or remove the old box as How to clean up segments shows.

"""The script of the guide "How to name a box"."""

from sharedbox import SegmentExistsError, SharedBox


class Motor(SharedBox, identity="example-motor"):
    position: int = 0


motor = Motor()
same = Motor.attach()
print(same.name == motor.name)  # True


class Settings(SharedBox, name="example-settings"):
    rate: float = 20.0


settings = Settings()
print(settings.name)  # example-settings

x_axis = Motor.create("example-x-axis")
y_axis = Motor.create("example-y-axis", 5)
y_view = Motor.attach("example-y-axis")
print(y_view.position)  # 5

try:
    Motor.create("example-x-axis")
except SegmentExistsError as error:
    print(error)  # a segment named 'example-x-axis' already exists; its creator, ...

for box in (motor, same, settings, x_axis, y_axis, y_view):
    box.close()
Motor.unlink()
Settings.unlink()
Motor.unlink("example-x-axis")
Motor.unlink("example-y-axis")