#!/usr/bin/env python3
import dict_to_table as dtt
from sys import argv

caption = "Function pointers from the \\texttt{node\_type} C structure (\\autoref{lst:struct_nodetype}), which are used to register node-type functions with the super-node."

ibverbs = {'start node-type':
          ['int (*start)(struct super_node *sn);',
           'This function is executed once when at least one instance of a certain node-type is present in the super-node. It can be used as global initialization to create shared resources for a certain node-type.'],

           'parse':
           ['int (*parse)(struct node *n, json_t *cfg);',
            'The number of instances to be created of a certain node-type and their settings are specified in a \\acrshort{json} file and decoded using the Jansson C library\\footnote{\\url{http://www.digip.org/jansson}}. This function is executed once for every instance of a node-type and shall interpret all settings which are passed to the instance via the parameter \\texttt{json\\_t *cfg}.'],

           'check':
           ['int (*check)(struct node *n);',
            'This function is executed once for every instance of a node-type and shall check if all previously parsed settings are valid.'],

           'start node':
           ['int (*start)(struct node *n);',
            'This function is executed once for every instance of a node-type and is used to initialize resources which are unique for every node.'],

           'print':
           ['char * (*print)(struct node *n);',
            'When invoked, this function shall return a string with a textual representation of this instance of the node-type.'],

           'reverse':
           ['int (*reverse)(struct node *n);',
            'This function may be called by the super-node between the parse- and the start-node-function. It will interchange the source and target address information and can be used to initialize a source and destination node-type instance with the same configuration file. This function is mainly used for debugging environments.'],

           'read':
           ['int (*read)(struct node *n, struct sample *smps[], unsigned cnt, unsigned *release);',
            'This function forms---together with the write-function---the core of every node-type instance. By calling this function, the super-node passes an empty structure which can hold \\texttt{cnt} samples. The node-type instance than fills \\texttt{*smps[]} with $0 < \\texttt{ret} < \\texttt{cnt}$ values, where \\texttt{ret} is also the value that is returned by the function.\
            \\newline\
            Every sample contains a reference counter which is incremented before the sample is passed to a node. Usually, after the read (or write) function returns, these samples are released for re-use by decrementing the reference counter. There are certain situations in which it is undesirable to release the samples after read (or write) is called. The \\texttt{*release} value lets the node define how many samples from \\texttt{*smps[]} may be released on return. \\texttt{*release} is initialized to \\texttt{cnt}; this indicates the default case in which all samples are released after the struct returns.\
            \\newline\
            An example of this situation for the InfiniBand node can be found in \\autoref{sec:villas_read}.'],

           'write':
           ['int (*write)(struct node *n, struct sample *smps[], unsigned cnt, unsigned *release);',
            'The parameters of this function are similar to those of the read-function. The super-node provides \\texttt{cnt} samples, which it wants the node to send to its target. The return value of this function indicates the number of samples which were successfully sent. By changing \\texttt{*release}, the node-type instance can define that only the first $\\texttt{*release}$ elements from \\texttt{*smps[]} should be released for re-use on return of the function.\
            \\newline\
            An example of this situation for the InfiniBand node can be found in \\autoref{sec:villas_write}.'],

           'fd':
           ['int (*fd)(struct node *n);',
            'This function must return a file descriptor, which enables the node to send notifications to the super-node. This is necessary when the super-node multiplexes incoming data from several nodes, and only wants to call a node\'s read-function when data is actually available.'],

           'stop node':
           ['int (*stop)(struct node *n);',
            'This function is the counterpart of \\texttt{int (*start)(struct node *n);} and shall be used to stop operation of the node-type instance.'],

           'destroy':
           ['int (*destroy)(struct node *n);',
            'This function is the counterpart of \\texttt{int (*start)(struct super\\_node *sn);} and can be used as global de-initialization of certain node-type.'],

           'stop node-type':
           ['int (*stop)();',
            'This function shall free the memory of an instance of a node-type.'],
           }


dtt.print_file(ibverbs, argv[0], caption, 500)