Author davin
Recipients brett.cannon, davin, eric.snow, giampaolo.rodola, lukasz.langa, nascheme, osvenskan, pitrou, pmpp, rhettinger, ronaldoussoren, skrah, terry.reedy, yselivanov
Date 2019-02-16.00:09:02
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1550275742.41.0.859781562817.issue35813@roundup.psfhosted.org>
In-reply-to
Content
Regarding the API of the SharedMemory class, its flags, mode, and read_only parameters are not universally enforced or simply not implemented on all platforms that offer POSIX Shared Memory or Windows Named Shared Memory.  A simplified API for the SharedMemory class that behaves consistently across all platforms would avoid confusion for users.  For users who have specific need of flags/mode/read_only controls on a platform that they know does indeed respect that control, they should still have a mechanism to leverage those controls.

I propose a simpler, consistent-across-platforms API like:
    SharedMemory(name=None, create=False, size=0)

    *name* and *size* retain their purpose though the former now defaults to None.
    *create* is set to False to indicate no new shared memory block is to be
    created because we only wish to attach to an already existing shared memory
    block.  When set to True, a new shared memory block will be created unless
    one already exists with the supplied unique name, in which case that block
    will be attached to and used.

    Example of attaching to an already existing shared memory block:
        SharedMemory(name='uniquename')
    Example of creating a new shared memory block where any new name will do:
        SharedMemory(create=True, size=128)
    Example of creating/attaching a shared memory block with a specific name:
        SharedMemory(name='specialsnowflake', create=True, size=4096)


Even with its simplified API, SharedMemory will continue to be powered by PosixSharedMemory on systems where "POSIX Shared Memory" is implemented and powered by NamedSharedMemory on Windows systems.  The API for PosixSharedMemory will remain essentially unchanged from its current form:
    PosixSharedMemory(name=None, flags=None, mode=0o600, size=0, read_only=False)
The API for NamedSharedMemory will be updated to no longer attempt to mirror its POSIX counterpart:
    NamedSharedMemory(name=None, create=False, size=0, read_only=False)

To be clear:  the inconsistencies motivating this proposed API change is *not* only arising from differences between Windows and POSIX-supporting systems.  For example, among systems implementing POSIX shared memory, the mode flag (which promises control over whether user/group/others can read/write to a shared memory block) is often but not always ignored; it differs from one OS to the next.


Alternatives/variations to this proposed API change:

* Leave the current APIs alone where all 3 classes have identical APIs.  Feedback in discussions and from those experimenting with the code suggests this is creating confusion.

* Change all 3 classes to have the matching APIs again.  This unnecessarily thwarts the ability of users to exploit functionality that they know to be there on specific target platforms that they care about.

* Do not expose flags/mode/read_only as part of the input paramemters to PosixSharedMemory/NamedSharedMemory but do expose them as class attributes instead.  This arguably makes things unnecessarily complicated.  This is not a simple topic but its complexity can be treated in a more straightforward way.

* Use a parameter name other than 'create' (e.g. 'attach_only') in the newly proposed API.

* Make all input parameters keyword-only for greater flexibility in the API in the future.
History
Date User Action Args
2019-02-16 00:09:02davinsetrecipients: + davin, brett.cannon, nascheme, rhettinger, terry.reedy, ronaldoussoren, pitrou, osvenskan, giampaolo.rodola, skrah, pmpp, lukasz.langa, eric.snow, yselivanov
2019-02-16 00:09:02davinsetmessageid: <1550275742.41.0.859781562817.issue35813@roundup.psfhosted.org>
2019-02-16 00:09:02davinlinkissue35813 messages
2019-02-16 00:09:02davincreate