Areas

Déclarations dans : be/kernel/OS.h

Librairie : libroot.so

Une area est un gros morceau de mémoire virtuelle qui peut être partagé entre threads (de différentes teams, peut-être). Si votre application a besoin d'allouer de grands blocs de mémoire, ou veut partager beaucoup de données avec une autre application, vous devriez envisager l'usage d'une area.

Pour plus d'informations sur les areas, consultez "Concepts des areas".

Pour des exemples de créations et de partage d'areas, consultez "Exemples d'usage d'une area".

Area Functions

area_for()

	area_id area_for(void *addr)

Retourne l'area qui contient l'adresse donnée (dans l'espace d'adresse de votre propre team). L'argument n'a pas besoin d'être l'adresse de début d'une area, ni d'être sur une limite de page mémoire : si l'adresse se trouve n'importe où dans une des areas de votre application, l'ID de cette area est retournée.

Puisque l'adresse est considérée dans l'espace d'adresse local, l'area qui est retournée sera également locale—elle aura été crée ou clonée par votre application.

CODES DE RETOUR

• B_ERROR. L'adresse ne reside pas dans une area.

Voir aussi : find_area()

clone_area()

	area_id clone_area(const char *clone_name,       void **clone_addr,       uint32 clone_addr_spec,       uint32 clone_protection,       area_id source_area)

Créer une nouvelle area (l'area clone) qui repose dans la même mémoire physique qu'une area pré-existante (l'area source).

• clone_name est le nom que vous voulez affecter à l'area clonée. Les noms d'area font, au plus, B_OS_NAME_LENGTH caractères.

• clone_addr pointe sur une valeur donnant l'adresse à laquelle vous voulez que l'area clonée démarre; la valeur pointée doit être un multiple de B_PAGE_SIZE (4096). La fonction modifie la valeur pointée par clone_addr à l'adresse réelle de début—elle peut être différente de celle que vous aviez demandé. La consistance de *clone_addr dépend de la valeur de clone_addr_spec, comme expliqué tout de suite.

• clone_addr_spec est une des quatre constantes qui décrivent comment clone_addr doit être interprétée. Les trois premières constantes, B_EXACT_ADDRESS, B_BASE_ADDRESS et B_ANY_ADDRESS, ont la signification expliquée dans create_area().

  La quatrième constante, B_CLONE_ADDRESS, indique que l'adresse de l'area clonée doit être la même que l'adresse de l'area source. Cloner l'adresse est commode si vous avez deux (ou plus) applications qui veulent s'échanger des pointeurs entre elles—en utilisant des adresses clonées, les applications n'ont pas à compenser les pointeurs qu'elles reçoivent. Pour les constantes B_ANY_ADDRESS et B_CLONE_ADDRESS, la valeur en entrée pointée par clone_addr est ignorée.

• clone_protection est l'une des constantes B_READ_AREA et B_WRITE_AREA, ou les deux combinées. Elles ont la même signification que pour create_area(); gardez à l'esprit, comme décrit ici, qu'une area clonée peut avoir une protection différente de celle de sa source.

• source_area est l' area_id de l'area que vous souhaitez cloner. Vous fournissez habituellement cette valeur en passant le nom d'une area à la fonction find_area().

L'area clonée hérite du schéma de verrouillage de l'area source.

Habituellement, l'area source et l'area clonée sont dans deux applications différentes. Il est possible de cloner une area depuis une area source existante dans la même application, mais il n'y a pas beaucoup de raison de faire ça sauf si vous voulez des protections différentes sur ces areas.

Si clone_area() réussie, l'area_id du clone est retournée. Sinon, elle retourne un code d'erreur descriptif, listé ci-dessous.

CODES DE RETOUR

• B_BAD_VALUE. Mauvaise valeur d'un argument; vous avez passé une constante non reconnue pour addr_spec ou lock, la valeur de *addr n'est pas un multiple de B_PAGE_SIZE, vous avez positionné addr_spec à B_EXACT_ADDRESS ou B_CLONE_ADDRESS mais l'adresse demandée n'a pas pu être satisfaite, ou source_area n'identifie pas une area existante.

• B_NO_MEMORY. Pas assez de mémoire pour allouer les structures système qui supportent cette area (peu probable).

• B_ERROR. Une autre erreur système a empêché le clonage de l'area.

Voir aussi : create_area()

create_area()

	area_id create_area(const char *name,       void **addr,       uint32 addr_spec,       uint32 size,       uint32 lock,       uint32 protection)

Créer une nouveau area et retourne son area_id.

• name est le nom que vous souhaitez donner à l'area. Ce nom n'a pas besoin d'être unique. Les noms d'areas font, au plus, B_OS_NAME_LENGTH (32) caractères.

• addr pointe sur l'adresse à laquelle vous souhaitez que l'area démarre. La valeur de *addr doit tomber sur une limite de page; autrement dit, elle doit être un entier multiple de B_PAGE_SIZE (4096). Notez que c'est un pointeur sur un pointeur : *addr—et non pas addr— doit être initialisée par l'adresse désirée; vous passez alors l'adresse de addr comme argument, comme montré ci-dessous :

      /* Initialiser l'adresse à une limite de page. */
      char * addr = (char *)(B_PAGE_SIZE * 100);
      
      /* Passez l'adresse de addr comme second argument. */
      create_area( "my area", &addr, ...);

La fonction modifie la valeur de *addr à l'adresse réelle de début de l'area—elle peut être différente de celle que vous aviez demandé. La consistance de *addr dépend de la valeur de addr_spec, comme expliqué tout de suite.

• addr_spec est une constante indiquant à la fonction comment la valeur de *addr doit être employée. Il y a trois constantes utiles de spécification d'adresse, et une qui ne s'emploit ici :

Constante	Signification
B_EXACT_ADDRESS	Vous voulez que la valeur de *addr soit prise littéralement et strictement. Si l'area ne peut pas être allouée à cette adresse, la fonction échoue.
B_BASE_ADDRESS	L'area peut démarrer à une adresse égale ou supérieure à *addr.
B_ANY_ADDRESS	L'adresse de début est déterminée par le système. Dans ce cas, la valeur pointée par addr est ignorée (en entrée de fonction).
B_ANY_KERNEL_ADDRESS	L'adresse de début est déterminée par le système, et la nouvelle area appartiendra à la team du Noyau; elle ne sera pas détruite lorsque l'application se terminera. Dans ce cas, la valeur pointée par addr est ignorée (en entrée de fonction).
B_CLONE_ADDRESS	N'est significatif que pour la fonction clone_area().

• size est la taille, en octets, de l'area. La taille doit être un entier multiple de B_PAGE_SIZE (4096). La limite supérieure de size dépend de l'espace de swap disponible (ou de RAM, si l'area doit y être verrouillée).

• lock décrit comment la mémoire physique de l'area doit être gérée vis à vis du swapping. Il y a quatre constantes de verrouillage :

Constante	Signification
B_FULL_LOCK	La mémoire est verrouillée dans la RAM lors de la création de l'area, et ne sera jamais swappée.
B_CONTIGUOUS	Non seulement la mémoire de l'area est verrouillée en RAM, mais elle est aussi garantie d'être contigue. C'est particulièrement—et peut-être exclusivement—utile pour les concepteurs de certains types de pilotes de périphériques.
B_LAZY_LOCK	Des pages individuelles de mémoire sont amenées en RAM dans l'ordre naturel des choses et alors verrouillées.
B_NO_LOCK	Les pages ne sont jamais verrouillées, elles sont amenées en RAM ou descendues (swappées) sur disque selon le besoin.
B_LOMEM	C'est une constante spéciale, utilisée pour les areas qui doivent être verrouillées, contigues, et résider dans les premiers 16 Mo de mémoire physique. Les gens qui ont besoin de cette constante se reconnaitront.

• protection est un masque binaire décrivant si la mémoire peut être modifiée et/ou lue. Vous formez le masque en ajoutant les constantes B_READ_AREA (l'area peut être lue) et B_WRITE_AREA (elle peut être modifiée). La protection choisie ne s'applique qu'à cette area. Si votre area est clonée, le clone peut choisir une protection différente.

Si create_area() réussie, l'area_id de la nouvelle area est retourné. Sinon, elle retourne un des codes d'erreur suivant :

CODES DE RETOUR

• B_BAD_VALUE. Mauvaise valeur d'un argument; vous avez passé une constante non reconnue pour addr_spec ou lock, la valeur de *addr ou size n'est pas un multiple de B_PAGE_SIZE, ou vous avez positionné addr_spec à B_EXACT_ADDRESS mais l'adresse demandée n'a pas pu être satisfaite.

• B_NO_MEMORY. Pas assez de mémoire pour allouer les structures système qui supportent cette area (peu probable), pas assez de mémoire physique pour supporter une area verrouillée, ou pas assez d'espace de swap pour allouer de la mémoire virtuelle (autrement dit, size est trop grand.)

• B_ERROR. Une autre erreur système a empêché la création de l'area.

Voir aussi : clone_area()

delete_area()

	status_t delete_area(area_id area)

Supprime l'area désignée. Si aucune autre area pointe sur la mémoire physique que cette area représente, la mémoire est libérée. Après la suppression, la valeur de area n'est plus un identifiant d'area valide.

Actuellement, n'importe qui peut détruire toute area—l'action n'est pas refusée si, par exemple, l'argument area_id a été créé par une autre application. Cette liberté sera retirée dans une prochaine version. Jusque là essayez d'eviter de détruire les areas d'autres applications.

CODES DE RETOUR

• B_OK. L'area a été détruite; area est maintenant invalide.

• B_ERROR. area n'identifie pas une area valide.

find_area()

	area_id find_area(const char *name)

Retourne une area dont le nom correspond avec l'argument. Les noms d'area n'ont pas besoin d'être uniques—des appels successifs à cette fonction avec le même argument peut très bien ne pas retourner le même area_id.

Ce que vous faites avec l'area trouvée dépend d'où elle vient :

• Si vous avez trouvé une area que votre propre application a créé ou cloné, vous pouvez utiliser l'ID retourné directement.

• Si l'area a été créée ou clonée par une autre application, vous devez immédiatement cloner l'area (sauf si vous en faites quelque chose de vraiment inoffensif, comme examiner simplement la structure d'information de l'area).

CODES DE RETOUR

• B_NAME_NOT_FOUND. L'argument n'identifie pas une area existante.

Voir aussi : area_for()

get_area_info() , get_next_area_info() , area_info

	status_t get_area_info(area_id area, area_info *info) status_t get_next_area_info(team_id team, int32 *cookie, area_info *info) struct {} area_info

Copient des informations sur une area particulière dans la structure area_info désignée par info. La première version de ces fonctions indique l'area directement, par son area_id.

La version get_next_area_info(), elle, vous permet de parcourir la liste de toutes les areas d'une team, par appel successifs. L'argument team identifie la team que vous voulez observer; une valeur 0 de team signifie la team du thread appelant. L'argument cookie est un marqueur, positionnez-le à 0 lors du premier appel, la fonction s'occupe du reste. Celle-ci retourne B_BAD_VALUE lorsqu'il n'y a plus d'areas à visiter :

   /* Obtenir l'area_info pour chaque area de cette team.  */
   area_info info;
   int32 cookie = 0;
   
   while (get_next_area_info(0, &cookie, &info) == B_OK)
      ...

La structure area_info est :

	typedef struct area_info {          area_id area;          char name[B_OS_NAME_LENGTH];          size_t size;          uint32 lock;          uint32 protection;          team_id team;          size_t ram_size;          uint32 copy_count;          uint32 in_count;          uint32 out_count;          void *address;       } area_info;

Les champs sont :

• area est l'area_id qui identifie l'area.

• name est le nom affecté à l'area lors de sa création ou son clonage.

• size est la taille (virtuelle) de l'area, en octets.

• lock est une constante représentant le schéma de verrouillage de l'area. Elle vaut B_FULL_LOCK, B_CONTIGUOUS, B_LAZY_LOCK, B_NO_LOCK, ou B_LOMEM.

• protection précise si la mémoire de l'area peut être lue ou modifiée. C'est une combinaison de B_READ_AREA et B_WRITE_AREA.

• team est le team_id de la team qui a créé ou cloné cette area.

• address est un pointeur sur l'adresse de début de l'area. Gardez à l'esprit que cette adresse n'est significative que pour la team qui a créé (ou cloné) l'area.

Les quatres derniers champs fournissent des informations sur l'area qui peuvent étre utiles pour diagnostiquer l'utilisation du système. Les champs sont particulièrement précieux si vous chasser des pertes mémoire :

• ram_size donne la quantité, en octets, de l'area présente actuellement en RAM.

• copy_count est un compteur de "duplication sur écriture" qui peut être ignoré—il ne s'applique pas aux areas que vous créez. Le système peut créer des areas avec "duplication sur écriture" (il le fait lorsqu'il charge la section des données d'un exécutable, par exemple), mais vous ne le pouvez pas.

• in_count est le nombre total de fois que des pages de l'area ont été chargées en RAM.

• out_count est le nombre total de fois que des pages de l'area ont été déchargées de la RAM (swappées).

CODES DE RETOUR

• B_OK. L'area a été trouvée; info contient des informations valides.

• B_BAD_VALUE. area n'identifie pas une area existante, team n'identifie pas une team existante, ou il n'y a plus d'area à visiter.

resize_area()

	status_t resize_area(area_id area, size_t new_size)

Modifie la taille de l'area désignée à new_size, exprimé en octets. L'argument new_size doit être un multiple de B_PAGE_SIZE (4096).

Les modifications de taille affecte la fin de la mémoire allouée existante de l'area : si vous augmentez la taille de l'area, la nouvelle mémoire est ajouté à la fin de l'area; si vous réduisez l'area, les pages en fin sont relâchées et libérées. En aucun cas l'adresse de début de l'area ne change, ni les données existantes dedans ne sont modifiées (excepté, bien sûr, pour les données perdues en raison d'une diminution).

Redimenssionner affecte toutes les areas qui réfèrent la mémoire physique de cette area. Par exemple, si B est un clone de A, et vous Redimenssionner A, B sera automatiquement redimenssionnée (si c'est possible).

CODES DE RETOUR

• B_OK. L'area a été redimenssionnée.

• B_BAD_VALUE. area n'identifie pas une area valide, ou new_size n'est pas un multiple de B_PAGE_SIZE.

• B_NO_MEMORY. Pas assez de mémoire pour supporter la nouvelle portion de l'area. Cela ne devrait arriver qu'uniquement si vous augmentez la taille de l'area.

• B_ERROR. Une autre erreur système a empêché le redimenssionnement de l'area.

set_area_protection()

	status_t set_area_protection(area_id area, uint32 new_protection)

Modifie les droits de lecture/écriture de l'area donnée. L'argument new_protection est un masque binaire indiquant l'une, l'autre ou les deux constantes B_READ_AREA et B_WRITE_AREA. La première signifie que l'area peut être lue; la seconde, qu'elle peut être modifiée. La protection d'une area ne s'applique uniquement aux accès à la mémoire sous-jacente par cette area spécifique. Des areas clones différentes se réfèrant à la même mémoire peuvent avoir des protections différentes.

CODES DE RETOUR

• B_OK. La protection est changée.

• B_BAD_VALUE. area n'identifie pas une area valide.