Simple Virtual Machine
A simple but flexible virtual machine
SVM synchronisation events

This module contains API functions to handle SVM synchronisation events. More...

Functions

SVM_FUNCTION SVM_Event_Queue svm_event_queue_new (const void *svm)
 This function creates an event queue. More...
 
SVM_FUNCTION SVM_Event_Queue_Address svm_event_address_new (const void *svm)
 This function creates an event queue address. More...
 
SVM_FUNCTION SVM_Event_Queue_Address svm_event_address_new_struct (const void *svm, const SVM_Structure structure)
 This function creates an event queue address. More...
 
SVM_FUNCTION SVM_Boolean svm_event_address_has_struct (const void *svm, const SVM_Event_Queue_Address address)
 This function checks whether an event queue address has an owner. More...
 
SVM_FUNCTION SVM_Structure svm_event_address_get_struct (const void *svm, const SVM_Event_Queue_Address address)
 This function retrieves the owner of an event queue address. More...
 
SVM_FUNCTION void svm_event_queue_join (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address address)
 This function lets an address to join the event queue. More...
 
SVM_FUNCTION void svm_event_queue_leave (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address address)
 This function lets an address to leave the event queue. More...
 
SVM_FUNCTION void svm_event_queue_push (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address destination, const SVM_Event_Queue_Address origin, const SVM_Structure event)
 This function pushes an event on a queue from an address to another address. More...
 
SVM_FUNCTION void svm_event_queue_broadcast (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address origin, const SVM_Structure event)
 This function pushes an event on a queue from an address to all addresses. More...
 
SVM_FUNCTION SVM_Boolean svm_event_queue_pull (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address destination, SVM_Event_Queue_Address *origin, SVM_Structure *event, const SVM_Boolean soft)
 This function pulls an event on a queue from an address. More...
 
SVM_FUNCTION SVM_Boolean svm_event_queue_check (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address destination, SVM_Event_Queue_Address *origin, SVM_Structure *event, const SVM_Value_Integer timeout, const SVM_Boolean soft)
 This function pulls an event on a queue from an address with a timeout in an integer value. More...
 
SVM_FUNCTION SVM_Boolean svm_event_queue_check__raw (const void *svm, SVM_Event_Queue event_queue, const SVM_Event_Queue_Address destination, SVM_Event_Queue_Address *origin, SVM_Structure *event, const unsigned long int timeout, const SVM_Boolean soft)
 This function pulls an event on a queue from an address with a timeout in a raw integer. More...
 

Detailed Description

This module contains API functions to handle SVM synchronisation events.

Function Documentation

◆ svm_event_address_get_struct()

SVM_FUNCTION SVM_Structure svm_event_address_get_struct ( const void *  svm,
const SVM_Event_Queue_Address  address 
)

This function retrieves the owner of an event queue address.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in]addressThe event queue address.

The owner of the address is returned. If the address was not associated to an owner, a FAILURE interruption is raised.

Returns
The owner of the event queue address.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the address has no owner.
See also
svm_structure_get_internal
svm_event_address_has_struct

◆ svm_event_address_has_struct()

SVM_FUNCTION SVM_Boolean svm_event_address_has_struct ( const void *  svm,
const SVM_Event_Queue_Address  address 
)

This function checks whether an event queue address has an owner.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in]addressThe event queue address.
Returns
TRUE when the address has an owner, FALSE otherwise.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
See also
svm_structure_get_internal

◆ svm_event_address_new()

SVM_FUNCTION SVM_Event_Queue_Address svm_event_address_new ( const void *  svm)

This function creates an event queue address.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.

The address is created without association to an owner.

Returns
The event queue address.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)

◆ svm_event_address_new_struct()

SVM_FUNCTION SVM_Event_Queue_Address svm_event_address_new_struct ( const void *  svm,
const SVM_Structure  structure 
)

This function creates an event queue address.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in]structureThe structure owner of the address.

The address is created with an association to an owner. Creating an address with a reference to its owner allows an event puller to reach the pusher of the event.

Note
The owner structure variable does not need to be set global.
Returns
The event queue address.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
See also
svm_structure_new

◆ svm_event_queue_broadcast()

SVM_FUNCTION void svm_event_queue_broadcast ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  origin,
const SVM_Structure  event 
)

This function pushes an event on a queue from an address to all addresses.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the event will be pushed.
[in]originThe address from which the event is sent.
[in]eventThe structure containing the event.

The event is pushed to the event queue.

Note
The event structure variable does not need to be set global.
Warning
The structure will be shared between all addresses.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the origin address has not joined the event queue.
See also
svm_structure_new

◆ svm_event_queue_check()

SVM_FUNCTION SVM_Boolean svm_event_queue_check ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  destination,
SVM_Event_Queue_Address origin,
SVM_Structure event,
const SVM_Value_Integer  timeout,
const SVM_Boolean  soft 
)

This function pulls an event on a queue from an address with a timeout in an integer value.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the event will be pushed.
[in]destinationThe address to which the event will be sent.
[out]originThe address from which the event is sent.
[out]eventThe structure containing the event.
[in]timeoutA timeout in milliseconds.
[in]softThe process is put in pause while waiting for an event.

The API function waits until an event is ready to be pulled or the timeout is reached. A timeout of 0 exists immediately if no event is ready to be pulled. When this API function is called within a process accepting interruption notifications, any interruption will stop the event pulling without a delivered message.

Warning
Accessing to origin and event when the API function has returned FALSE will result in an undefined behavior.
Returns
TRUE when an event has been delivered to the destination address, FALSE otherwise.
Note
The soft parameter shall be set to FALSE when the lock is used at least once inside a scheduler, and should be set to TRUE otherwise.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the destination address has not joined the event queue.
FAILUREinterruption when the timeout is a negative integer.
FAILUREinterruption when this API function is called outside a kernel.
See also
svm_structure_get_internal
svm_process_interruptionnotification_enable

◆ svm_event_queue_check__raw()

SVM_FUNCTION SVM_Boolean svm_event_queue_check__raw ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  destination,
SVM_Event_Queue_Address origin,
SVM_Structure event,
const unsigned long int  timeout,
const SVM_Boolean  soft 
)

This function pulls an event on a queue from an address with a timeout in a raw integer.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the event will be pushed.
[in]destinationThe address to which the event will be sent.
[out]originThe address from which the event is sent.
[out]eventThe structure containing the event.
[in]timeoutA timeout in milliseconds.
[in]softThe process is put in pause while waiting for an event.

The API function waits until an event is ready to be pulled or the timeout is reached. A timeout of 0 exists immediately if no event is ready to be pulled.

Warning
Accessing to origin and event when the API function has returned FALSE will result in an undefined behavior.
Returns
TRUE when an event has been delivered to the destination address, FALSE otherwise.
Note
The soft parameter shall be set to FALSE when the lock is used at least once inside a scheduler, and should be set to TRUE otherwise.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the destination address has not joined the event queue.
FAILUREinterruption when the timeout is a negative integer.
FAILUREinterruption when this API function is called outside a kernel.
See also
svm_structure_get_internal

◆ svm_event_queue_join()

SVM_FUNCTION void svm_event_queue_join ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  address 
)

This function lets an address to join the event queue.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the address will be added.
[in]addressThe address.

This step is done by the owner of the address. It is required to push events to this address and to pull events from this address.

Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)

◆ svm_event_queue_leave()

SVM_FUNCTION void svm_event_queue_leave ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  address 
)

This function lets an address to leave the event queue.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the address will be removed.
[in]addressThe address.

This step is done by the owner of the address to close its participation to the event queue.

Note
All pending events are discarded.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)

◆ svm_event_queue_new()

SVM_FUNCTION SVM_Event_Queue svm_event_queue_new ( const void *  svm)

This function creates an event queue.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.

This event queue allows synchronisation of a lot of concurrent processes by pushing events to this queue and pulling events from this queue.

Each process accessing the queue will be identified by an address linked to a structure.

Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)

◆ svm_event_queue_pull()

SVM_FUNCTION SVM_Boolean svm_event_queue_pull ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  destination,
SVM_Event_Queue_Address origin,
SVM_Structure event,
const SVM_Boolean  soft 
)

This function pulls an event on a queue from an address.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the event will be pushed.
[in]destinationThe address to which the event will be sent.
[out]originThe address from which the event is sent.
[out]eventThe structure containing the event.
[in]softThe process is put in pause while waiting for an event.

The API function waits until an event is ready to be pulled. When this API function is called within a process accepting interruption notifications, any interruption will stop the event pulling without a delivered message.

Warning
Accessing to origin and event when the API function has returned FALSE will result in an undefined behavior.
Returns
TRUE when an event has been delivered to the destination address, FALSE otherwise.
Note
The soft parameter shall be set to FALSE when the lock is used at least once inside a scheduler, and should be set to TRUE otherwise.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the destination address has not joined the event queue.
FAILUREinterruption when this API function is called outside a kernel.
See also
svm_structure_get_internal
svm_process_interruptionnotification_enable

◆ svm_event_queue_push()

SVM_FUNCTION void svm_event_queue_push ( const void *  svm,
SVM_Event_Queue  event_queue,
const SVM_Event_Queue_Address  destination,
const SVM_Event_Queue_Address  origin,
const SVM_Structure  event 
)

This function pushes an event on a queue from an address to another address.

Parameters
[in]svmThe SVM pointer passed as first argument of the callback function.
[in,out]event_queueThe event queue on which the event will be pushed.
[in]destinationThe address to which the event will be sent.
[in]originThe address from which the event is sent.
[in]eventThe structure containing the event.

The event is pushed to the event queue.

Note
The event structure variable does not need to be set global.
Exceptions
FAILUREinterruption when a parameter is incorrect. (Please refer to the main description page of this API.)
FAILUREinterruption when the origin or the destination address has not joined the event queue.
See also
svm_structure_new