Ports

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

Librairie : libroot.so

Un port est un dépot de messages global au système dans lequel tout thread peut y copier un buffer de données, et dont tout thread peut en obtenir le buffer. Ce dépot est implémenté comme une file FIFO (premier entré/premier sorti—first-in/first-out) : un port stocke ses messages dans l'ordre de leur réception, et il les libère dans le même ordre. Chaque port possède sa propre file.

Les ports sont largement encapsulés par la classe BMessage (et ses classes relatives) du kit d'Application. Les deux avantages des ports que vous ne pouvez pas obtenir au niveau du BMessage sont :

• Les ports vous laissent définir la taille de la file de messages.

• Les ports peuvent être utilisés dans du code C (au lieu du C++).

Pour la plupart des applications, ceci n'est pas essentiel.

Pour plus d'information sur les ports, consultez "Concepts d'un port".

Fonctions

create_port()

	port_id create_port(int32 queue_length, const char *name)

Créer un nouveau port et retourne son port_id. Le nom du port est name et la taille de sa file de messages est queue_length. Ni le nom ni la taille de la file de messages ne peuvent être changées par la suite. Le nom ne doit pas dépasser B_OS_NAME_LENGTH (32) caractères.

En indiquant la taille de la file de messages d'un port, vous indiquez combien de messages il pourra contenir à un même instant. Lorsque la file est remplie—lorsqu'elle contient queue_length messages—les appels ultérieurs à write_port() (sur ce port) bloqueront tant qu'aucune place n'est faite dans la file (via des appels à read_port()) pour acceuillir les messages additionnels. Lorsque la taille de la file d'un port est spécifiée par create_port(), elle ne peut plus être changée.

Cette fonction rend la team du thread appelant propriétaire du port. La propriété peut être plus tard transferée via la fonction set_port_owner(). Lorsque le propriétaire d'un port meurt (lorsque tous les threads de cette team sont morts), le port est automatiquement détruit. Si vous voulez détruire un port avant la mort de son propriétaire, utilisez la fonction delete_port() .

CODES DE RETOUR

• B_BAD_VALUE. queue_length est trop grande ou inférieure à zéro.

• B_NO_MORE_PORTS. Le système n'a pas pu allouer un autre port.

close_port()

	status_t close_port(port_id port)

Ferme le port afin qu'aucun autre message ne puisse y être écrit. Après sa fermeture, vous pouvez appeller read_port() sur le port, mais un appel à write_port() retournera B_BAD_PORT_ID. Vous ne pouvez pas réouvrir un port fermé; vous appellez cette fonction afin de lire les messages non-lus du port avant de le détruire, tout en étant assuré qu'aucun nouveau message n'apparaitra. Après avoir lu les messages, vous devez appeller delete_port() sur ce port.

CODES DE RETOUR

• B_OK. port est maintenant clos.

• B_BAD_PORT_ID. port n'identifie pas un port ouvert.

delete_port()

	status_t delete_port(port_id port)

Détruit le port spécifié. La file de messages du port peut ne pas être vide—vous pouvez détruire un port contenant des messages non-lus. Les threads bloqués dans des appels à read_port() ou write_port() sur ce port sont automatiquement débloqués (et reçoivent B_BAD_PORT_ID en valeur de retour).

Le thread qui appelle delete_port() n'a pas besoin d'être membre de la team propriétaire du port; n'importe quel thread peut détruire n'importe quel port.

CODES DE RETOUR

• B_OK. Le port a été détruit.

• B_BAD_PORT_ID. port n'est pas un port valide.

find_port()

	port_id find_port(const char *port_name)

Retourne le port_id du port ainsi nommé. port_name ne doit pas dépasser 32 caractères (B_OS_NAME_LENGTH).

CODES DE RETOUR

• B_NAME_NOT_FOUND. Aucun port existant n'a comme nom port_name.

get_port_info() , get_next_port_info()

	status_t get_port_info(port_id port, port_info *info) status_t get_next_port_info(team_id team,       uint32 *cookie,       port_info *info)

Copient des informations sur un port particulier dans la structure port_info désignée par info. La première version de ces fonctions indique le port directement, par son port_id.

La version get_next_port_info(), elle, vous permet de parcourir la liste de tous les ports 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 de port à visiter :

   /* Obtenir le port_info pour chaque port de cette team. */
   port_info info;
   int32 cookie = 0;
   
   while (get_next_port_info(0, &cookie, &info) == B_OK)
      ...

L'information dans la structure port_info est garantie consistente en interne, mais l'ensemble de la structure doit être considérée comme non &agave; jour dès que vous la recevez. Elle fournit une photo du port tel qu'il était juste avant le retour de la fonction.

CODES DE RETOUR

• B_OK. Le port a été trouvé; info contient des informations valides.

• B_BAD_VALUE. port n'identifie pas un port existant, team n'identifie pas une team existante, ou il n'y plus de port à visiter.

port_buffer_size() , port_buffer_size_etc()

	ssize_t port_buffer_size(port_id port) ssize_t port_buffer_size_etc(port_id port,       uint32 flags,       bigtime_t timeout)

Ces fonctions retournent la taille (en octets) du buffer de message en tête de file de messages du port. Vous appellez cette fonction afin d'allouer un buffer suffisament grand pour recupérer les données du message.

La fonction port_buffer_size() bloque si le port est actuellement vide. Elle se débloque lorsqu'un appel à write_port() lui donne un buffer à mesurer (même si le buffer fait 0 octet de long), ou lorsque le port est détruit.

La fonction port_buffer_size_etc() vous permet de préciser le temps maximum d'attente par la fonction qu'un message se présente. Pour activer cette limite, vous passez B_TIMEOUT comme argument flags, et affecter à timeout le temps, en micro secondes, que vous voulez bien attendre.

CODES DE RETOUR

• B_BAD_PORT_ID. port n'identifie pas un port existant, ou le port a été détruit pendant que la fonction était bloquée.

• B_TIMED_OUT. La limite de timeout a été atteinte.

• B_WOULD_BLOCK. Vous avez demandé un timeout de 0, mais il y a aucun message dans la file.

Voir aussi : read_port()

port_count()

	int32 port_count(port_id port)

Retourne le nombre de messages actuellement dans la file de messages du port. C'est le nombre de messages qui ont été écrits dans le port par des appels à write_port() mais qui n'ont pas encore été lus via des appels read_port() correspondants.

Cette fonction est livrée principalement comme commodité et comme un outil semi-fiable de deboggage. La valeur qu'elle retourne est par nature peu fiable : il n'y a aucune garantie que des appels additionnels à read_port() ou write_port() ne changeront pas le nombre pendant le retour de cette fonction.

CODES DE RETOUR

• B_BAD_PORT_ID. port n'identifie pas un port existant.

Voir aussi : get_port_info()

read_port() , read_port_etc()

	ssize_t read_port(port_id port,       int32 *msg_code,       void *msg_buffer,       size_t buffer_size) ssize_t read_port_etc(port_id port,       int32 *msg_code,       void *msg_buffer,       size_t buffer_size,       uint32 flags,       bigtime_t timeout)

Ces fonctions retirent le message en tête de file de messages du port et copient le contenu du message dans les arguments msg_code et msg_buffer. La taille du buffer msg_buffer, en octets, est donnée par buffer_size. C'est à l'appelant de s'assurer que le buffer de message est assez grand pour recevoir le message qui sera lu. Si vous voulez un conseil sur la taille du message, vous devriez appeller port_buffer_size() avant d'appeler ces fonctions.

Si la file de messages du port est vide lors de votre appel à read_port(), la fonction bloquera. Elle reviendra lorsque qu'un autre thread aura écrit un message dans le port via write_port(). Une lecture bloquée est également débloquée si le port est détruit.

La fonction read_port_etc() vous permet de préciser le temps maximum d'attente par la fonction qu'un message se présente. Pour activer cette limite, vous passez B_TIMEOUT comme argument flags, et affecter à timeout le temps, en micro secondes, que vous voulez bien attendre.

CODES DE RETOUR

Un appel réussi retourne le nombre d'octets qui ont été recopiés dans l'argument msg_buffer.

• B_BAD_PORT_ID. port n'identifie pas un port existant, ou le port a été détruit pendant que la fonction était bloquée.

• B_TIMED_OUT. La limite de timeout a été atteinte.

• B_WOULD_BLOCK. Vous avez demandé un timeout de 0, mais il y a aucun message dans la file.

Voir aussi : write_port(), port_buffer_size()

set_port_owner()

	status_t set_port_owner(port_id port, team_id team)

Transfère la propriété du port désigné à une autre team. Un port ne peut être la propriété d'une seule team à la fois; en positionnant le propriétaire d'un port, vous le retirez de son propriétaire actuel.

Il n'y pas de restrictions sur qui peut être propriétaire d'un port, ou sur qui peut transférer la propriété. Autrement dit, le thread qui appelle set_port_owner() n'a pas besoin d'être membre de la team actuellement propriétaire du port, et vous n'êtes pas obligé d'affecter des ports uniquement à la team du thread appelant (bien que ces deux cas sont les scénarios les plus probables).

La propriété d'un port est significatif pour une raison : lorsqu'une team meurt (lorsque tous ces threads sont morts), les ports possèdés par cette team son détruits. La propriété, mis à part cela, n'a pas d'autre importance—elle n'apporte aucun privilèges spéciaux ou obligations.

Pour découvrir le propriétaire d'un port, utilisez la fonction get_port_info().

CODES DE RETOUR

• B_OK. La propriété a été transmise.

• B_BAD_PORT_ID. port n'identifie pas un port valide.

• B_BAD_TEAM_ID. team n'identifie pas une team valide.

Voir aussi : get_port_info()

write_port() , write_port_etc()

	status_t write_port(port_id port,       int32 msg_code,       void *msg_buffer,       size_t buffer_size) status_t write_port_etc(port_id port,       int32 msg_code,       void *msg_buffer,       size_t buffer_size,       uint32 flags,       bigtime_t timeout)

Ces fonctions placent un message à la fin de la file de messages du port. Le message consiste en un msg_code et un msg_buffer :

• msg_code contient le "code de message". C'est un masque, un drapeau ou toute autre valeur prévisible donnant une représentation générale du type de message.

• msg_buffer est un pointeur sur un buffer qui peut être utilisé pour fournir des informations complémentaires. Vous passez la taille de ce buffer, en octets, par l'argument buffer_size. Le buffer peut être de taille quelconque.

Si la file de messages du port est pleine lors de votre appel à write_port(), la fonction bloquera. Elle reviendra lorsqu'un read_port() libèrera un emplacement dans la file pour le nouveau message. Un write_port() bloqué reviendra également si le port cible est détruit ou fermé.

La fonction write_port_etc() vous permet de préciser le temps maximum d'attente par la fonction d'un emplacement libre pour le message. Pour activer cette limite, vous passez B_TIMEOUT comme argument flags, et affecter à timeout le temps, en micro secondes, que vous voulez bien attendre.

CODES DE RETOUR

• B_OK. L'écriture dans le port a réussie.

• B_BAD_PORT_ID. port n'identifie pas un port existant, ou le port a été détruit pendant que la fonction était bloquée.

• B_TIMED_OUT. La limite de timeout a été atteinte.

• B_WOULD_BLOCK. Vous avez demandé un timeout de 0, mais il n'y a plus d'emplacement libre dans la file de messages.

Voir aussi : read_port()

Structures et Constantes

port_info

	struct {       port_id port;       team_id team;       char name[B_OS_NAME_LENGTH];       int32 capacity;          int32 queue_count;       int32 total_count;       } port_info

La structure port_info fournit des informations sur un port. Vous obtenez l'une de ces structures au moyen de get_port_info() ou de get_next_port_info().

• port. Le port_id du port.

• team. Le team_id du propriétaire du port.

• name. Le nom affecté à ce port.

• capacity. La taille de la file de messages du port.

• queue_count. Le nombre de messages actuellement dans la file.

• total_count. Le nombre total de messages lus depuis ce port.

Notez que total_count n'inclut pas les messages actuellement dans la file du port.