Here we will introduce you to the PDI functions and what you should expect them to do.
As mentioned in Specification tree we have to provide specification tree to instruct PDI what data we will share and what to do with it. We want to show what happens on each PDI API call. We will use Trace plugin, which is very simple plugin that just prints every information it gets. Let's create a specification tree named
hello_event.yml that will load trace plugin:
Yes, that is whole specification tree. Trace plugin prints everything, so there is no need to specify what we want it to do.
We need to write a source code of our application:
Let's analyze what happens in each line. Firstly we have PDI_init() function which take parameter of type
PC_tree_t. It's a tree structure parsed from some YAML file, in our case we parse it with
paraconf library build in PDI. To parse a file we need to call
PC_parse_path function passing file path as argument. The next step is to call an event in PDI named "Hello World Event". At the end we have to call PDI_finalize(). The output from this program is presented below:
The first line indicates that plugin has loaded successfully. The second is PDI message, that tells it managed to create all descriptors and load all defined plugins. Then we have message from loaded trace plugin which printed the event name it has received. The next information is from PDI and indicates that finalization has started and now it will deallocate resources. Last message is from trace plugin destructor.
In Hello Event we learned how to call an event. In this chapter we will see how to share and reclaim data.
Firstly we have to create a specification tree named
data and trace plugin tree declared:
We have declared trace plugin and one descriptor named
world of integer type. Now let's write our program:
Let's analyze new functions:
PDI_shareshares access to the variable with PDI. The first argument is a descriptor name and indicates what data we are sharing. The second one is pointer to our variable and the last one is access direction.
PDI_OUTmeans data direction from application to PDI,
PDI_INis a direction from PDI to the program,
PDI_INOUTincludes both directions.
PDI_reclaimreclaims the share which means that PDI will no longer have access to shared variable. As an argument it takes name of the descriptor.
The output from our application:
As we can see from the logs above, when we called
PDI_share plugin gained access to the shared variable and after
PDI_reclaim the variable has become no longer available for the plugin. The share notification gives plugin possibility to operate on data dependently what has been declared in specification tree.
The same exact result we can achieve with
PDI_expose which is just
PDI_share call and right after
PDI_reclaim is called.
is the same as:
Now we will try to access a descriptor we share with PDI. In this case we won't need any plugin. We want to define string in our
Now let's write some simple program:
We will focus on
print_secret_msg function. If you don't understand what happens in
main function, please see Hello Data example.
PDI_access sets our pointer to the data location. We need to pass
PDI_IN because data flows from PDI to our application. We also want to use
PDI_reclaim would end the sharing status of this descriptor and we reclaim this data later in
main function. Output from the program:
As you can see, we manage to access data descriptor from function only by passing its name and correct direction access.
In some cases we would want to expose many descriptors at once. For this we have multi expose which shares all the given descriptors, then call given event and then reclaim all passed data. Let's look at the example.
We have defined 3 descriptors and trace plugin. Now it's time for our application:
First argument of the
PDI_multi_expose is the event name we want to call when all the descriptors are shared. After this we pass in loop:
The output of the execution:
The logs from trace plugin confirm the execution order we were expecting.