64 lines
5.0 KiB
Python
64 lines
5.0 KiB
Python
|
#!/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)
|