PDI 1.8.0-alpha.2024-08-11

the PDI data interface

Code annotation

The code annotation API is the main interface to use in the code. More...

Enumerations

enum  PDI_inout_t {
  PDI_NONE = 0 ,
  PDI_IN = 1 ,
  PDI_OUT = 2 ,
  PDI_INOUT = 3
}
 Access directions. More...
 

Functions

PDI_status_t PDI_share (const char *name, void *data, PDI_inout_t access)
 Shares some data with PDI.
 
PDI_status_t PDI_access (const char *name, void **buffer, PDI_inout_t inout)
 Requests for PDI to access a data buffer.
 
PDI_status_t PDI_release (const char *name)
 Releases ownership of a data shared with PDI.
 
PDI_status_t PDI_reclaim (const char *name)
 Reclaims ownership of a data buffer shared with PDI.
 
PDI_status_t PDI_event (const char *event)
 Triggers a PDI "event".
 
PDI_status_t PDI_expose (const char *name, void *data, PDI_inout_t access)
 Shortly exposes some data to PDI.
 
PDI_status_t PDI_multi_expose (const char *event_name, const char *name, void *data, PDI_inout_t access,...)
 Performs multiple exposes at once.
 

Detailed Description

The code annotation API is the main interface to use in the code.

It offers functions that can be called from code with no side effect by default and that can therefore be considered as annotations.

Enumeration Type Documentation

◆ PDI_inout_t

Access directions.

Enumerator
PDI_NONE 

No data transfert.

PDI_IN 

data tranfer from PDI to the main code

PDI_OUT 

data transfer from the main code to PDI

PDI_INOUT 

data transfer in both direction

Function Documentation

◆ PDI_share()

PDI_status_t PDI_share ( const char *  name,
void *  data,
PDI_inout_t  access 
)

Shares some data with PDI.

The user code should not modify it before a call to either PDI_release or PDI_reclaim.

Parameters
[in]namethe data name
[in,out]datathe accessed data
[in]accesswhether the data can be accessed for read or write by PDI
Returns
an error status
Precondition
the user code owns the data buffer
Postcondition
ownership of the data buffer is shared between PDI and the user code

the access parameter is a binary OR of PDI_IN & PDI_OUT.

  • PDI_IN means PDI can set the buffer content
  • PDI_OUT means the buffer contains data that can be accessed by PDI

◆ PDI_access()

PDI_status_t PDI_access ( const char *  name,
void **  buffer,
PDI_inout_t  inout 
)

Requests for PDI to access a data buffer.

Parameters
[in]namethe data name
[in,out]buffera pointer to the accessed data buffer
[in]inoutthe access properties (PDI_IN, PDI_OUT, PDI_INOUT)
Returns
an error status
Precondition
PDI owns the data buffer
Postcondition
ownership of the data buffer is shared between PDI and the user code

◆ PDI_release()

PDI_status_t PDI_release ( const char *  name)

Releases ownership of a data shared with PDI.

PDI is then responsible to free the associated memory whenever necessary.

Parameters
[in]namename of the data to release
Returns
an error status
Precondition
ownership of the data buffer is shared between PDI and the user code
PDI owns the data buffer

◆ PDI_reclaim()

PDI_status_t PDI_reclaim ( const char *  name)

Reclaims ownership of a data buffer shared with PDI.

PDI does not manage the buffer memory anymore.

Parameters
[in]namename of the data to reclaim
Returns
an error status
Precondition
ownership of the data buffer is shared between PDI and the user code
Postcondition
the user code owns the data buffer

◆ PDI_event()

PDI_status_t PDI_event ( const char *  event)

Triggers a PDI "event".

Parameters
[in]eventthe event name
Returns
an error status

◆ PDI_expose()

PDI_status_t PDI_expose ( const char *  name,
void *  data,
PDI_inout_t  access 
)

Shortly exposes some data to PDI.

Equivalent to PDI_share + PDI_reclaim.

Parameters
[in]namethe data name
[in]datathe exposed data
[in]accesswhether the data can be accessed for read or write by PDI
Returns
an error status

◆ PDI_multi_expose()

PDI_status_t PDI_multi_expose ( const char *  event_name,
const char *  name,
void *  data,
PDI_inout_t  access,
  ... 
)

Performs multiple exposes at once.

All the data is shared in order they were specified and reclaimed in reversed order after an event is triggered.

NULL argument indicates an end of the list.

Parameters
[in]event_namethe name of the event that will be triggered when all data become available
[in]namethe data name
[in]datathe exposed data
[in]accesswhether the data can be accessed for read or write by PDI
[in]...(additional arguments) additional list of data to expose, each should contain name, data and access, NULL argument inidactes an end of the list.
Returns
an error status