mbind(2) System Calls Manual mbind(2)

mbind - Définir la politique mémoire pour une zone de mémoire

Bibliothèque de règles NUMA (Non-Uniform Memory Access) (libnuma, -lnuma)

#include <numaif.h>
long mbind(void addr[.size], unsigned long size, int mode,
           const unsigned long nodemask[(.maxnode + ULONG_WIDTH - 1)
/ ULONG_WIDTH],
           unsigned long maxnode, unsigned int flags);

mbind() sets the NUMA memory policy, which consists of a policy mode and zero or more nodes, for the memory range starting with addr and continuing for size bytes. The memory policy defines from which node memory is allocated.

If the memory range specified by the addr and size arguments includes an "anonymous" region of memory—that is a region of memory created using the mmap(2) system call with the MAP_ANONYMOUS—or a memory-mapped file, mapped using the mmap(2) system call with the MAP_PRIVATE flag, pages will be allocated only according to the specified policy when the application writes (stores) to the page. For anonymous regions, an initial read access will use a shared page in the kernel containing all zeros. For a file mapped with MAP_PRIVATE, an initial read access will allocate pages according to the memory policy of the thread that causes the page to be allocated. This may not be the thread that called mbind().

La politique spécifiée sera ignorée pour toute projection MAP_SHARED dans la plage mémoire spécifiée. Les pages seront plutôt allouées conformément à la politique de mémoire du thread qui a fait que la page a été allouée. Cela peut ne pas être le thread qui a appelé mbind().

Si la plage de mémoire spécifiée inclut une région de mémoire partagée créée avec l'appel système shmget(2) et attachée avec l'appel système shmat(2), les pages allouées pour la région de mémoire anonyme ou partagée seront allouées conformément à la politique spécifiée, sans se soucier du processus attaché au segment de mémoire partagé qui a provoqué l'allocation. Si toutefois la région de mémoire partagée a été créée avec l'attribut SHM_HUGETLB, les grosses pages seront allouées conformément à la politique spécifiée seulement si l'allocation de pages est provoquée par le processus qui a appelé mbind() pour cette région.

Par défaut, mbind() n'a d'effet que sur les nouvelles allocations ; s'il y a déjà eu un accès aux pages dans la plage avant de configurer la politique, alors la politique n'a pas d'effet. Ce comportement par défaut peut être écrasé par les attributs MPOL_MF_MOVE et MPOL_MF_MOVE_ALL décrits plus loin.

The mode argument must specify one of MPOL_DEFAULT, MPOL_BIND, MPOL_INTERLEAVE, MPOL_WEIGHTED_INTERLEAVE, MPOL_PREFERRED, MPOL_PREFERRED_MANY, or MPOL_LOCAL (which are described in detail below). All policy modes except MPOL_DEFAULT require the caller to specify the node or nodes to which the mode applies, via the nodemask argument.

L'argument mode peut aussi contenir des attributs optionnels. Les valeurs possibles sont :

Quand mode est MPOL_BIND, activer l’équilibrage NUMA du noyau pour la tâche s’il est géré par le noyau. Si l'attribut n'est pas pris en charge par le noyau ou est utilisé avec un autre mode que MPOL_BIND, -1 est renvoyé et errno est positionné sur EINVAL.
Un paramètre nodemask non vide indique des identifiants de nœuds physiques. Linux ne réassocie pas nodemask quand le thread change de contexte de cpuset ou après une modification de l'ensemble de nœuds autorisés par le contexte de cpuset en cours du thread.
Un paramètre nodemask non vide indique des identifiants de nœuds relatifs à l'ensemble des identifiants de nœuds autorisés par le cpuset en cours du thread.

nodemask pointe sur un masque de bits qui contient jusqu'à maxnode bits. La taille du masque de bits est arrondie au multiple supérieur de sizeof(unsigned long), mais le noyau n'utilisera que jusqu'à maxnode bits. Une valeur NULL pour nodemask ou une valeur maxnode de zéro indique un ensemble vide de nœuds. Si la valeur de maxnode est zéro, l'argument nodemask est ignoré. Quand un nodemask est exigé, il doit contenir au moins un nœud de connecté, autorisé dans le contexte de cpuset en cours du thread appelant (à moins que le drapeau MPOL_F_STATIC_NODES ne soit fourni) et doit contenir de la mémoire.

Le paramètre mode doit contenir une des valeurs suivantes :

Ce mode demande à ce que toute politique n'étant pas une politique par défaut soit retirée, ce qui restaure le comportement par défaut. Lorsqu'il est appliqué à une plage mémoire à l’aide de mbind(), cela signifie d'utiliser la politique mémoire du thread qui peut être définie avec set_mempolicy(2). Si le mode de la politique de mémoire du thread est également MPOL_DEFAULT, la politique par défaut du système sera utilisée. La politique par défaut du système alloue des pages sur le nœud du processeur qui a déclenché l'allocation. Pour MPOL_DEFAULT, les paramètres nodemask et maxnode doivent spécifier l'ensemble vide de nœuds.
Ce mode spécifie une politique stricte qui restreint l'allocation mémoire aux nœuds indiqués dans nodemask. Si nodemask indique plus d'un nœud, les allocations de pages se feront à partir du nœud ayant assez d'espace libre et étant le plus proche de celui où elles ont lieu. Il n'y aura pas d'allocation de pages à partir de nœuds non indiqués dans nodemask (avant Linux 2.6.26, les allocations de pages se faisaient d'abord à partir du nœud dont l'identifiant numérique était le plus petit jusqu'à ce que ce nœud ne contienne plus de mémoire libre. Les allocations se faisaient ensuite à partir du nœud dont l'identifiant était le prochain plus grand spécifié dans nodemask et ainsi de suite jusqu'à ce que plus un seul nœud indiqué ne contienne de mémoire libre).
Ce mode spécifie que les allocations de pages sont entrelacées à travers l'ensemble de nœuds spécifiés dans nodemask. Cela optimise la bande passante au lieu de la latence en étalant les pages et l'accès mémoire à ces pages à travers plusieurs nœuds. Pour être efficace, la zone mémoire doit être relativement grande, au moins 1 Mo ou plus avec un modèle d'accès assez uniforme. Les accès à une unique page de la zone seront toujours limités à la capacité mémoire d'un seul nœud.
Ce mode entrelace les affectations de pages à travers les nœuds indiqués dans nodemask selon leur poids dans /sys/kernel/mm/mempolicy/weighted_interleave. Par exemple, si les bits 0, 2 et 5 sont positionnés dans nodemask, et si le contenu de /sys/kernel/mm/mempolicy/weighted_interleave/node0, de /sys/.../node2, and /sys/.../node5 sont respectivement de 4, 7 et 9, les pages de cette région seront affectées aux nœuds 0, 2 et 5 selon un ratio de 4:7:9.
Ce mode définit le nœud préféré pour les allocations. Le noyau essaiera d'abord d'allouer sur ce nœud, avant de ce rabattre sur d'autres nœuds si celui-ci n'a plus assez de mémoire libre. Si nodemask précise plus d'un identifiant de nœud, le premier nœud du masque sera choisi comme le nœud préféré. Si les paramètres nodemask et maxnode indiquent un ensemble vide, la mémoire est allouée sur le nœud du processeur qui a déclenché l'allocation.
Specifies a set of nodes for allocation; see set_mempolicy(2)
Ce mode indique « allocation locale » ; la mémoire est allouée sur le nœud du processeur qui a déclenché l'allocation (le « nœud local »). Les paramètres nodemask et maxnode doivent indiquer un ensemble vide. Si le « nœud local » possède peu de mémoire libre, le noyau essaiera d'allouer de la mémoire à partir d'autres nœuds. Le noyau allouera de la mémoire du « nœud local » à chaque fois qu'il y en aura de disponible. Si le « nœud local » n'est pas autorisé par le contexte de cpuset actuel du thread, le noyau essaiera d'allouer de la mémoire à partir d'autres nœuds. Le noyau allouera de la mémoire à partir du « nœud local » à chaque fois qu'il y sera autorisé par le contexte de cpuset actuel du thread. Au contraire, MPOL_DEFAULT ramène à la politique mémoire du thread (qui peut être définie par set_mempolicy(2)) ; il peut s'agir d'une autre politique que l'« allocation locale ».

Si l'option MPOL_MF_STRICT est passée dans flags et si mode n'est pas MPOL_DEFAULT, l'appel échoue avec l'erreur EIO si les pages de la plage mémoire ne suivent pas la politique.

Si MPOL_MF_MOVE est passé dans flags, le noyau essaiera de déplacer toutes les pages existantes dans la plage de mémoire pour qu'elles suivent la politique. Les pages partagées avec d'autres processus ne sont pas déplacées. Si MPOL_MF_STRICT est également indiqué, l'appel échouera avec l'erreur EIO si certaines pages ne peuvent pas être déplacées. Si la politique MPOL_INTERLEAVE a été spécifiée, les pages résidant déjà sur les nœuds spécifiés ne sont pas déplacés de sorte qu'ils sont entrelacés.

Si MPOL_MF_MOVE_ALL est indiqué dans flags, alors le noyau essaiera de déplacer toutes les pages existantes dans la plage mémoire, même si d'autres processus les utilisent. Le thread appelant doit être privilégié (avoir la capacité CAP_SYS_NICE) pour utiliser cette option. Si MPOL_MF_STRICT est également utilisé, l'appel renverra l'erreur EIO si certaines pages ne peuvent pas être déplacées. Si la politique MPOL_INTERLEAVE a été spécifiée, les pages résidant déjà sur les nœuds spécifiés ne sont pas déplacés de sorte qu'ils sont entrelacés.

S'il réussit, mbind() renvoie 0. En cas d'erreur, il renvoie -1 et remplit errno avec la valeur d'erreur.

Part or all of the memory range specified by nodemask and maxnode points outside your accessible address space. Or, there was an unmapped hole in the specified memory range specified by addr and size.
An invalid value was specified for flags or mode; or addr + size was less than addr; or addr is not a multiple of the system page size. Or, mode is MPOL_DEFAULT and nodemask specified a nonempty set; or mode is MPOL_BIND or MPOL_INTERLEAVE and nodemask is empty. Or, maxnode exceeds a kernel-imposed limit. Or, nodemask specifies one or more node IDs that are greater than the maximum supported node ID. Or, none of the node IDs specified by nodemask are on-line and allowed by the thread's current cpuset context, or none of the specified nodes contain memory. Or, the mode argument specified both MPOL_F_STATIC_NODES and MPOL_F_RELATIVE_NODES.
MPOL_MF_STRICT a été utilisé et une page existante était déjà sur un nœud ne suivant pas la politique ; ou soit MPOL_MF_MOVE soit MPOL_MF_MOVE_ALL a été spécifié et le noyau n'a pas été capable de déplacer toutes les pages existantes dans la plage.
La mémoire disponible du noyau n'était pas suffisante.
Le paramètre flags incluait l'attribut MPOL_MF_MOVE_ALL et l'appelant n'avait pas le privilège CAP_SYS_NICE.

Linux.

Linux 2.6.7.

La gestion de politique pour les pages immenses a été ajoutée dans Linux 2.6.16. Pour que la politique d'entrelacement soit efficace sur les projections de pages immenses, la taille de la zone mémoire doit être au moins de dizaines de mégaoctets.

Avant Linux 5.7. MPOL_MF_STRICT était ignoré sur les projections de pages immenses.

MPOL_MF_MOVE et MPOL_MF_MOVE_ALL ne sont disponibles qu'à partir de Linux 2.6.16.

Consultez numa(7) pour des informations sur la prise en charge par des bibliothèques.

La politique NUMA n'est pas gérée sur les plages de fichiers projetés en mémoire qui ont été projetées avec l'attribut MAP_SHARED.

Le mode MPOL_DEFAULT peut avoir des effets différents sur mbind() et sur set_mempolicy(2). Lorsque MPOL_DEFAULT est spécifié pour set_mempolicy(2), la politique mémoire du thread est remise à la politique par défaut du système ou l'allocation locale. Lorsque MPOL_DEFAULT est spécifié pour une plage de mémoire utilisant mbind(), toutes les pages allouées par la suite pour cette plage utiliseront la politique du thread telle qu'elle a été définie par set_mempolicy(2). Cela supprime de manière effective la politique explicite de la plage spécifiée, ce qui peut éventuellement remettre une politique autre que celle par défaut. Pour choisir explicitement une « allocation locale » pour une plage mémoire, spécifiez mode de MPOL_LOCAL ou MPOL_PREFERRED avec un ensemble vide de nœuds. Cette méthode fonctionnera aussi avec set_mempolicy(2).

get_mempolicy(2), getcpu(2), mmap(2), set_mempolicy(2), shmat(2), shmget(2), numa(3), cpuset(7), numa(7), numactl(8)

La traduction française de cette page de manuel a été créée par Christophe Blaess https://www.blaess.fr/christophe/, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Philippe MENGUAL <jpmengual@debian.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.

21 février 2025 Pages du manuel de Linux 6.12