POD2-FR

 view release on metacpan or  search on metacpan

FR/perlxs.pod  view on Meta::CPAN

La variable RETVAL est une variable magique qui est toujours du type
retourné par la fonction de la librairie C. Le compilateur B<xsubpp>
fournit cette variable dans chaque XSUB et l'utilise par défaut pour y
mettre la valeur de retour de la fonction C appelée. Dans les cas
simples, la valeur de RETVAL sera mise dans ST(0) sur la pile
d'arguments, où Perl le recevra comme valeur de retour de la XSUB.

Si la XSUB a un type de retour égal à C<void>, le compilateur ne
fournira pas de variable RETVAL pour cette fonction. Lorsqu'on utilise
la directive PPCODE:, la variable RETVAL n'est plus nécessaire, sauf
si on l'utilise explicitement.

Si la directive PPCODE: n'est pas utilisée, la valeur de retour
C<void> devrait être utilisée uniquement pour des sous-routines qui ne
renvoient pas de valeur, I<même si> la directive CODE: est utilisée
pour positionner ST(0) explicitement.

Dans des versions plus anciennes de ce document, on conseillait
d'utiliser la valeur de retour C<void> dans de tels cas. On a
découvert que cela pouvait mener à des segfaults lorsque la XSUB était
I<vraiment> C<void>. Cette pratique est maintenant désapprouvée, et
risque de ne plus être supportée dans une version future. Utilisez la
valeur de retour C<SV *> dans ces cas-là (C<xsubpp> contient

FR/perlxs.pod  view on Meta::CPAN

                       host = (char *)SvPV(ST(1), PL_na);
                  RETVAL = rpcb_gettime( host, &timep );
          OUTPUT:
          timep
          RETVAL

=head2 Le mot-clé C_ARGS

Le mot-clé C_ARGS permet de réaliser des XSUB que l'on n'appelle pas
de la même manière depuis Perl que depuis C, sans qu'il soit
nécessaire d'écrire une section CODE: ou PPCODE:. Le contenu du
paragraphe C_ARGS est passé comme argument à la fonction C, sans aucun
changement.

Supposons par exemple que la fonction C soit déclarée ainsi :

    symbolic nth_derivative(int n, symbolic function, int flags);

et que la valeur par défaut de I<flags> soit contenue dans la variable
C I<default_flags>. Supposons que vous souhaitiez réaliser une
interface que l'on appellera de la manière suivante :

FR/perlxs.pod  view on Meta::CPAN

Pour cela, déclarez la XSUB ainsi :

    symbolic
    nth_derivative(function, n)
        symbolic        function
        int             n
    C_ARGS:
        n, function, default_flags

=head2 Le mot-clé PPCODE

Le mot-clé PPCODE: est une variante du mot-clé CODE: qui est utilisée
pour indiquer au compilateur B<xsubpp> que le programmeur fournit le
code contrôlant la pile des arguments pour les valeurs de retour des
XSUB. On souhaite parfois que la XSUB renvoie une liste de valeurs et
non une valeur unique. Dans ce cas-là, il faut utiliser PPCODE: et
rajouter de manière explicite la liste des valeurs sur la pile. Les
mots-clés PPCODE: et CODE: ne sont pas utilisés simultanément dans la
même XSUB.

La XSUB suivante appelle la fonction C rpcb_gettime() et renvoie à Perl
ses deux valeurs de sortie, timep et status, comme une seule liste.

     void
     rpcb_gettime(host)
          char *host
          PREINIT:
          time_t  timep;
          bool_t  status;
          PPCODE:
          status = rpcb_gettime( host, &timep );
          EXTEND(SP, 2);
          PUSHs(sv_2mortal(newSViv(status)));
          PUSHs(sv_2mortal(newSViv(timep)));

Remarquez que le programmeur doit fournir le code C assurant l'appel
de la vraie fonction rpcb_gettime(), ainsi que le placement correct
des valeurs de retour sur la pile des arguments.

Le type de retour C<void> pour cette fonction indique au compilateur
B<xsubpp> que la variable RETVAL n'est pas nécessaire, qu'elle n'est
pas utlisée, et qu'elle ne devrait pas être créée. Dans la plupart des
cas, il faut utiliser le type de retour void avec l'instruction
PPCODE:.

On utilise la macro EXTEND() afin de dégager de la place sur la pile
des arguments pour les 2 valeurs de retour. L'instruction PPCODE: fait
en sorte que le compilateur B<xsubpp> crée un pointeur vers la pile
dans la variable C<SP> ; c'est ce pointeur qui est utilisé dans la
macro EXTEND(). Les valeurs sont ensuite rajoutées sur la pile avec
les macros PUSHs().

A présent, la fonction rpcb_gettime() peut être utilisée depuis Perl
avec l'instruction suivante.

     ($status, $timep) = rpcb_gettime("localhost");

Lorsque vous travaillez sur les paramètres en sortie avec une section
PPCODE:, assurez-vous de traiter l'effet 'set'
convenablement. Consultez L<perlguts> pour plus de détails sur cet
effet 'set'.

=head2 Renvoyer undef et des listes vides

Le programmeur voudra parfois renvoyer simplement C<undef> ou une
liste vide si la fonction échoue, plutôt qu'une valeur d'état à
part. La fonction rpcb_gettime() présente justement cette
situation. Nous aimerions que la fonction retourne l'heure si elle
réussit, ou undef si elle échoue. Dans le code Perl suivant, la valeur

FR/perlxs.pod  view on Meta::CPAN

          bool_t x;
          CODE:
          ST(0) = sv_newmortal();
          if( rpcb_gettime( host, &timep ) ){
               sv_setnv( ST(0), (double)timep);
          }
          else{
               ST(0) = &PL_sv_undef;
          }

Pour renvoyer une liste vide, il faut utiliser un bloc PPCODE: et ne
pas rajouter de valeur de retour sur la pile.

     void
     rpcb_gettime(host)
          char *host
          PREINIT:
          time_t  timep;
          PPCODE:
          if( rpcb_gettime( host, &timep ) )
               PUSHs(sv_2mortal(newSViv(timep)));
          else{
          /* Rien n'est remis sur la pile, donc une */
          /* liste vide est renvoyee implicitement */
          }

Certaines personnes préfèrent rajouter un C<return> explicite dans la
XSUB ci-dessus au lieu de laisser l'exécution se poursuivre jusqu'au
bout. Dans ce cas-là, il convient plutôt d'utiliser C<XSRETURN_EMPTY>,

FR/perlxs.pod  view on Meta::CPAN

compilateur B<xsubpp> requis pour compiler le module XS. Un module XS
contenant l'instruction suivante ne pourra être compilé qu'avec une
version de B<xsubpp> égale ou supérieure à 1.922 :

        REQUIRE: 1.922

=head2 Le mot-clé CLEANUP

Ce mot-clé peut être utilisé quand une XSUB doit exécuter des
procédures de nettoyage spéciales avant de se terminer. Quand le
mot-clé CLEANUP: est utilisé, il doit suivre tout bloc CODE:, PPCODE:
ou OUTPUT: présent dans la XSUB. Les instructions spécifiées dans le bloc de
nettoyage seront les dernières instructions de la XSUB.

=head2 Le mot-clé BOOT

Le mot-clé BOOT: permet de rajouter du code dans la fonction
d'amorçage de l'extension.  La fonction d'amorçage est générée par le
compilateur B<xsubpp> et contient normalement les instructions
nécessaires pour enregistrer toute XSUB auprès de Perl. Avec le
mot-clé BOOT:, le programmeur peut dire au compilateur de rajouter des

FR/perlxs.pod  view on Meta::CPAN

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t &timep
          OUTPUT:
          timep

=head2 Insérer des commentaires et des directives de pré-processeur C

Des directives de pré-processeur C peuvent prendre place à l'intérieur
des blocs BOOT:, PREINIT:, INIT:, CODE:, PPCODE: et CLEANUP:, de même
qu'en dehors des fonctions. Les commentaires sont autorisés partout
après le mot-clé MODULE. Le compilateur transmet les directives de
pré-processeur sans modification et supprime les lignes commentées.

On peut rajouter des commentaires dans les XSUB en mettant un C<#> sur
une ligne comme premier caractère non blanc. Attention, le commentaire
ne doit pas ressembler à une directive de pré-processeur C, sinon il
sera interprété comme tel. Le moyen le plus simple d'éviter cela
consiste à mettre des caractères blancs devant le C<#>.