multiprocessing.shared_memory --- Shared memory for direct access across processes

Code source : Lib/multiprocessing/shared_memory.py

Nouveau dans la version 3.8.

Ce module fournit une classe, SharedMemory, pour l'allocation et la gestion de mémoire partagée entre un ou plusieurs processus sur une machine à plusieurs cœurs ou à multiprocesseurs (architecture symmetric multiprocessor ou SMP). Pour faciliter la gestion du cycle de vie de la mémoire partagée, tout particulièrement entre plusieurs processus, le module multiprocessing.managers fournit aussi la classe SharedMemoryManager, sous-classe de BaseManager.

Dans ce module, il faut entendre « mémoire partagée » au sens de « blocs de mémoire partagée à la mode System V » (même si l'implémentation peut différer), et non au sens de « mémoire distribuée ». Ce type de mémoire partagée permet à plusieurs processus d'écrire dans une zone commune (ou « partagée ») de la mémoire vive. Normalement, les processus n'ont accès qu'à leur propre espace mémoire ; la mémoire partagée permet justement le partage de données entre des processus, ce qui leur évite d'avoir à s'envoyer ces données par message. Échanger des données par mémoire partagée peut amener des gains de performance substantiels par rapport aux échanges via le disque dur, des connecteurs ou d'autres canaux qui nécessitent de sérialiser et de désérialiser les données.

class multiprocessing.shared_memory.SharedMemory(name=None, create=False, size=0)

Crée un nouveau bloc de mémoire partagée ou enregistre un bloc déjà existant. Un nom unique doit être donné à chaque bloc de mémoire partagée ; ainsi, un processus peut créer un nouveau bloc de mémoire partagée avec un nom fixé et un autre processus peut enregistrer le même bloc, à partir de son nom.

Puisque qu'il permet de partager des données entre processus, un bloc de mémoire partagée peut survivre au processus qui l'a créé. Lorsqu'un processus n'a plus besoin d'un bloc — qui peut toujours être en cours d'utilisation par un autre — il doit appeler la méthode close(). Quand tous les processus ont fini d'utiliser ce bloc, il faut appeler la méthode unlink() pour le libérer.

name est le nom (une chaîne de caractères) unique de la mémoire partagée à allouer. Lors de la création d'un nouveau bloc mémoire, si None (valeur par défaut) est passé comme nom, un nouveau nom est généré.

create indique si un nouveau bloc doit être alloué (True) ou si on enregistre un bloc déjà existant (False).

size définit le nombre d'octets à allouer. Comme certaines plates-formes choisissent d'allouer les blocs mémoire en multiples de la taille de la page mémoire de la plate-forme, la taille réellement allouée peut être supérieure à la taille demandée. Lors de l'enregistrement d'un bloc déjà existant, le paramètre size est ignoré.

close()

Empêche les accès ultérieurs à la mémoire partagée depuis cette instance ; toutes les instances doivent appeler close() pour s'assurer que les ressources sont bien libérées. Notez qu'appeler close() ne libère pas la mémoire elle-même.

Initie la libération de la mémoire partagée sous-jacente. Pour être sûr que les ressources sont libérées correctement, unlink() doit être appelée une (et une seule) fois par tous les processus qui ont utilisé le bloc partagé. Après avoir initié la destruction d'un bloc mémoire, le bloc peut ne pas être détruit immédiatement ; ce comportement dépend de la plate-forme. Accéder aux données d'un bloc de mémoire partagée après l'appel à unlink() peut provoquer une erreur mémoire. Notez que le dernier processus à libérer le bloc mémoire de mémoire partagée peut appeler unlink() et close() dans n'importe quel ordre.

buf

Une memoryview du contenu du bloc de mémoire partagée.

name

Nom unique du bloc de mémoire partagée (lecture seule).

size

Taille en octets du bloc de mémoire partagée (lecture seule).

L'exemple qui suit montre un exemple d'utilisation bas niveau d'instances de SharedMemory :

>>> from multiprocessing import shared_memory
>>> shm_a = shared_memory.SharedMemory(create=True, size=10)
>>> type(shm_a.buf)
<class 'memoryview'>
>>> buffer = shm_a.buf
>>> len(buffer)
10
>>> buffer[:4] = bytearray([22, 33, 44, 55])  # Modify multiple at once
>>> buffer[4] = 100                           # Modify single byte at a time
>>> # Attach to an existing shared memory block
>>> shm_b = shared_memory.SharedMemory(shm_a.name)
>>> import array
>>> array.array('b', shm_b.buf[:5])  # Copy the data into a new array.array
array('b', [22, 33, 44, 55, 100])
>>> shm_b.buf[:5] = b'howdy'  # Modify via shm_b using bytes
>>> bytes(shm_a.buf[:5])      # Access via shm_a
b'howdy'
>>> shm_b.close()   # Close each SharedMemory instance
>>> shm_a.close()
>>> shm_a.unlink()  # Call unlink only once to release the shared memory

The following example demonstrates a practical use of the SharedMemory class with NumPy arrays, accessing the same numpy.ndarray from two distinct Python shells:

>>> # In the first Python interactive shell
>>> import numpy as np
>>> a = np.array([1, 1, 2, 3, 5, 8])  # Start with an existing NumPy array
>>> from multiprocessing import shared_memory
>>> shm = shared_memory.SharedMemory(create=True, size=a.nbytes)
>>> # Now create a NumPy array backed by shared memory
>>> b = np.ndarray(a.shape, dtype=a.dtype, buffer=shm.buf)
>>> b[:] = a[:]  # Copy the original data into shared memory
>>> b
array([1, 1, 2, 3, 5, 8])
>>> type(b)
<class 'numpy.ndarray'>
>>> type(a)
<class 'numpy.ndarray'>
>>> shm.name  # We did not specify a name so one was chosen for us
'psm_21467_46075'

>>> # In either the same shell or a new Python shell on the same machine
>>> import numpy as np
>>> from multiprocessing import shared_memory
>>> # Attach to the existing shared memory block
>>> existing_shm = shared_memory.SharedMemory(name='psm_21467_46075')
>>> # Note that a.shape is (6,) and a.dtype is np.int64 in this example
>>> c = np.ndarray((6,), dtype=np.int64, buffer=existing_shm.buf)
>>> c
array([1, 1, 2, 3, 5, 8])
>>> c[-1] = 888
>>> c
array([  1,   1,   2,   3,   5, 888])

>>> # Back in the first Python interactive shell, b reflects this change
>>> b
array([  1,   1,   2,   3,   5, 888])

>>> # Clean up from within the second Python shell
>>> del c  # Unnecessary; merely emphasizing the array is no longer used
>>> existing_shm.close()

>>> # Clean up from within the first Python shell
>>> del b  # Unnecessary; merely emphasizing the array is no longer used
>>> shm.close()
>>> shm.unlink()  # Free and release the shared memory block at the very end
class multiprocessing.managers.SharedMemoryManager([address[, authkey]])

Une sous-classe de BaseManager pour gérer des blocs de mémoire partagée entre processus.

Un appel à start() depuis une instance SharedMemoryManager lance un nouveau processus dont le seul but est de gérer le cycle de vie des blocs mémoires qu'il a créés. La méthode shutdown() de l'instance déclenche la libération de tous les blocs mémoires gérés par ce processus. Elle appelle SharedMemory.unlink() sur tous les objets SharedMemory gérés par ce processus et l'arrête ensuite. Créer des instances de SharedMemory par l'intermédiaire d'un SharedMemoryManager évite d'avoir à gérer et à libérer manuellement les ressources mémoire partagées.

Cette classe fournit des méthodes pour créer et renvoyer des instances de SharedMemory et pour créer des objets compatibles liste (ShareableList) basés sur la mémoire partagée.

Référez-vous à multiprocessing.managers.BaseManager pour la description des arguments optionnels hérités address et authkey, et comment ceux-ci doivent être utilisés pour enregistrer un service de SharedMemoryManager depuis un autre processus.

SharedMemory(size)

Crée et renvoie un nouvel objet SharedMemory de taille size octets.

ShareableList(sequence)

Crée et renvoie un nouvel objet ShareableList, initialisé à partir des valeurs de la sequence en entrée.

L'exemple qui suit illustre les mécanismes de base de SharedMemoryManager :

>>> from multiprocessing.managers import SharedMemoryManager
>>> smm = SharedMemoryManager()
>>> smm.start()  # Start the process that manages the shared memory blocks
>>> sl = smm.ShareableList(range(4))
>>> sl
ShareableList([0, 1, 2, 3], name='psm_6572_7512')
>>> raw_shm = smm.SharedMemory(size=128)
>>> another_sl = smm.ShareableList('alpha')
>>> another_sl
ShareableList(['a', 'l', 'p', 'h', 'a'], name='psm_6572_12221')
>>> smm.shutdown()  # Calls unlink() on sl, raw_shm, and another_sl

L'exemple suivant montre comment utiliser un objet SharedMemoryManager avec l'instruction with pour être sûr que tous les blocs mémoire sont libérés quand ils ne sont plus nécessaires. C'est souvent plus pratique que l'exemple précédent :

>>> with SharedMemoryManager() as smm:
...     sl = smm.ShareableList(range(2000))
...     # Divide the work among two processes, storing partial results in sl
...     p1 = Process(target=do_work, args=(sl, 0, 1000))
...     p2 = Process(target=do_work, args=(sl, 1000, 2000))
...     p1.start()
...     p2.start()  # A multiprocessing.Pool might be more efficient
...     p1.join()
...     p2.join()   # Wait for all work to complete in both processes
...     total_result = sum(sl)  # Consolidate the partial results now in sl

Lors de l'utilisation d'un SharedMemoryManager dans une instruction with, les blocs de mémoire partagée créés par ce gestionnaire sont tous libérés quand les instructions à l'intérieur du bloc with ont été exécutées.

class multiprocessing.shared_memory.ShareableList(sequence=None, *, name=None)

Construit un objet muable compatible avec le type liste dont toutes les valeurs sont stockées dans un bloc de mémoire partagée. Ceci limite le type des valeurs pouvant être stockées aux types natifs int, float, bool, str (de moins de 10 Mo chacune), bytes (de moins de 10 Mo chacun) et None. Une autre différence majeure avec une list native réside dans le fait qu'il est impossible de changer la taille (c.-à-d. pas d'ajout en fin de liste, ni d'insertion etc.) et qu'il n'est pas possible de créer de nouvelles instances de ShareableList par découpage.

sequence sert à créer une nouvelle ShareableList avec des valeurs. Mettez-le à None pour enregistrer une ShareableList déjà existante, en renseignant son nom unique.

name est le nom unique de la mémoire partagée demandée, tel que décrit dans la définition de SharedMemory. Pour enregistrer une ShareableList déjà existante, renseignez le nom unique du bloc de mémoire partagée et laissez sequence à None.

count(value)

Renvoie le nombre d’occurrences de value.

index(value)

Renvoie l'indice de la première occurrence de value. Lève une ValueError si value n'est pas présent.

format

Attribut en lecture seule contenant le format d’agrégation struct utilisé par les valeurs déjà stockées.

shm

Instance de SharedMemory dans laquelle les valeurs sont stockées.

L'exemple qui suit illustre un cas d'usage de base d'une instance de ShareableList :

>>> from multiprocessing import shared_memory
>>> a = shared_memory.ShareableList(['howdy', b'HoWdY', -273.154, 100, None, True, 42])
>>> [ type(entry) for entry in a ]
[<class 'str'>, <class 'bytes'>, <class 'float'>, <class 'int'>, <class 'NoneType'>, <class 'bool'>, <class 'int'>]
>>> a[2]
-273.154
>>> a[2] = -78.5
>>> a[2]
-78.5
>>> a[2] = 'dry ice'  # Changing data types is supported as well
>>> a[2]
'dry ice'
>>> a[2] = 'larger than previously allocated storage space'
Traceback (most recent call last):
  ...
ValueError: exceeds available storage for existing str
>>> a[2]
'dry ice'
>>> len(a)
7
>>> a.index(42)
6
>>> a.count(b'howdy')
0
>>> a.count(b'HoWdY')
1
>>> a.shm.close()
>>> a.shm.unlink()
>>> del a  # Use of a ShareableList after call to unlink() is unsupported

L'exemple ci-dessous montre comment un, deux ou un grand nombre de processus peuvent accéder à une ShareableList commune à partir du nom du bloc mémoire partagé sous-jacent :

>>> b = shared_memory.ShareableList(range(5))         # In a first process
>>> c = shared_memory.ShareableList(name=b.shm.name)  # In a second process
>>> c
ShareableList([0, 1, 2, 3, 4], name='...')
>>> c[-1] = -999
>>> b[-1]
-999
>>> b.shm.close()
>>> c.shm.close()
>>> c.shm.unlink()

L'exemple ci-dessous montre comment une ShareableList (et le SharedMemory sous-jacent) peut être sérialisée et désérialisée. Gardez bien à l'esprit que c'est toujours le même objet, car l'objet désérialisé a le même nom unique et est tout simplement attaché à un objet déjà existant du même nom (si cet objet est toujours en vie).

>>> import pickle
>>> from multiprocessing import shared_memory
>>> sl = shared_memory.ShareableList(range(10))
>>> list(sl)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

>>> deserialized_sl = pickle.loads(pickle.dumps(sl))
>>> list(deserialized_sl)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

>>> sl[0] = -1
>>> deserialized_sl[1] = -2
>>> list(sl)
[-1, -2, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(deserialized_sl)
[-1, -2, 2, 3, 4, 5, 6, 7, 8, 9]

>>> sl.shm.close()
>>> sl.shm.unlink()