PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

58.3. Exécution de parcours personnalisés

Lorsqu'un CustomScan est exécuté, l'état de son exécution est représenté par un CustomScanState, qui est déclaré comme suit :

typedef struct CustomScanState
{
    ScanState ss;
    uint32    flags;
    const CustomExecMethods *methods;
} CustomScanState;

ss est initialisé comme tous les autres états de parcours, sauf que si le parcours est pour une jointure plutôt qu'une relation, ss.ss_currentRelation est laissé à NULL. flags est un masque de bits avec la même signification que dans CustomPath et CustomScan. methods doit pointer vers un objet (généralement alloué statiquement) implémentant les méthodes requises d'un état de parcours personnalisé, qui sont détaillées ci-dessous. Typiquement, une structure CustomScanState, qui n'a pas besoin de supporter la fonction copyObject, sera actuellement une structure plus grande incorporant la structure ci-dessus comme premier membre.

58.3.1. Fonction callbacks d'exécution d'un parcours personnalisé

void (*BeginCustomScan) (CustomScanState *node,
                         EState *estate,
                         int eflags);

Complète l'initialisation de la structure CustomScanState. Les champs standards ont été initialisés par la fonction ExecInitCustomScan, mais tous les champs privés devraient être initialisés ici.

TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);

Récupère la ligne suivante du parcours. Si il existe des lignes restantes, la fonction devrait remplir pg_ResultTupleSlot avec la ligne suivante dans le sens actuel du parcours, puis renvoyer le slot de la ligne. Dans le cas contraire, NULL ou un slot vide devrait être renvoyé.

void (*EndCustomScan) (CustomScanState *node);

Nettoie les données privées associées avec le CustomScanState. Cette méthode est obligatoire, mais elle n'a pas besoin de faire quoi que ce soit si il n'y a pas de données associées ou des données qui seront nettoyées automatiquement.

void (*ReScanCustomScan) (CustomScanState *node);

Repositionne au début le parcours en cours et prépare à parcourir de nouveau la relation.

void (*MarkPosCustomScan) (CustomScanState *node);

Enregistre la position du parcours courant de telle manière qu'elle puisse être restaurée par la fonction callback RestrPosCustomScan. Cette fonction callback est facultative, et n'a besoin d'être fournie que si le drapeau CUSTOMPATH_SUPPORT_MARK_RESTORE est positionné.

void (*RestrPosCustomScan) (CustomScanState *node);

Restaure la position précédente du parcours telle que sauvegardée par la fonction MarkPosCustomScan. Cette fonction callback est facultative, et n'a besoin d'être fournie que si le drapeau CUSTOMPATH_SUPPORT_MARK_RESTORE est positionné.

Size (*EstimateDSMCustomScan) (CustomScanState *node,
                               ParallelContext *pcxt);

Estime la quantité de mémoire partagée dynamique qui sera requise pour l'opération parallèlisée. Elle pourrait être plus importante que la quantité rééellement utilisée, mais elle ne doit pas être moindre. La valeur en retour est en octets. Cette fonction est optionnelle. Elle n'est nécessaire que si ce type de parcours supporte une exécution parallélisée.

void (*InitializeDSMCustomScan) (CustomScanState *node,
                                 ParallelContext *pcxt,
                                 void *coordinate);

Initialise la mémoire partagée dynamique requise pour une opération parallélisée. L'argument coordinate pointe vers une partie de la mémoire partagée de taille identique à la valeur en retour de EstimateDSMCustomScan. Cette fonction est optionnelle. Elle n'est nécessaire que si ce type de parcours supporte une exécution parallélisée.

void (*ReInitializeDSMCustomScan) (CustomScanState *node,
                                   ParallelContext *pcxt,
                                   void *coordinate);

Ré-initialise la mémoire partagée dynamique requise pour des opérations parallélisées lorsque le noeud du plan pour le parcours personnalisé doit être réalisé de nouveau. Cette fonction est optionnelle et doit seulement être fournie si le fournisseur de ce parcours personnalisé supporte les exécutions parallélisées. La pratique recommandée est que cette fonction réinitialise seulement l'état partagé alors que la fonction ReScanCustomScan réinitialise seulement l'état local. Actuellement, cette fonction sera appelée avant ReScanCustomScan mais il est préférable de ne pas se fier à l'ordre des opérations.

void (*InitializeWorkerCustomScan) (CustomScanState *node,
                                    shm_toc *toc,
                                    void *coordinate);

Initialise un état local d'un processus en parallèle basé sur la configuration de l'état partagée dans le processus principal par InitializeDSMCustomScan. Cette fonction est optionnelle. Elle n'est nécessaire que si le fournisseur de ce parcours personnalisé supporte une exécution parallélisée.

void (*ShutdownCustomScan) (CustomScanState *node);

Libère les ressources quand il est anticipé que le nœud ne sera pas exécuté entièrement. Cette fonction ne sera pas appelée dans tous les cas; parfois, EndCustomScan peut être appelée sans que cette ait été appelée avant. Puisque le segment DSM utilisé par les requêtes parallèles est détruit juste après que ce callback soit appelé, les modules de parcours personnalisés qui désirent effectuer des actions avant que le segment DSM disparaissent devraient implémenter cette méthode.

void (*ExplainCustomScan) (CustomScanState *node,
                           List *ancestors,
                           ExplainState *es);

Envoie sur la sortie des informations additionnelles pour la commande EXPLAIN d'un nøeud du plan d'un parcours personnalisé. Cette fonction est facultative. Les données communes enregistrées dans la structure ScanState, tel que la liste des cibles et la relation parcourue, seront montrées même sans cette fonction callback, mais la fonction permet l'affichage d'états additionnels, privés.