Simple Virtual Machine A simple but flexible virtual machine

Functions
SVM synchronisation events
SVM synchronisation

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] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | address | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | address | The event queue address.

Returns
  TRUE when the address has an owner, FALSE otherwise.

Exceptions

  FAILURE | interruption 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] | svm | The 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

  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | structure | The 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

  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the event will be pushed.
  [in] | origin | The address from which the event is sent.
  [in] | event | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the event will be pushed.
  [in] | destination | The address to which the event will be sent.
  [out] | origin | The address from which the event is sent.
  [out] | event | The structure containing the event.
  [in] | timeout | A timeout in milliseconds.
  [in] | soft | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when the destination address has not joined the event queue.
  FAILURE | interruption when the timeout is a negative integer.
  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the event will be pushed.
  [in] | destination | The address to which the event will be sent.
  [out] | origin | The address from which the event is sent.
  [out] | event | The structure containing the event.
  [in] | timeout | A timeout in milliseconds.
  [in] | soft | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when the destination address has not joined the event queue.
  FAILURE | interruption when the timeout is a negative integer.
  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the address will be added.
  [in] | address | The 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

  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the address will be removed.
  [in] | address | The 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

  FAILURE | interruption 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] | svm | The 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

  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the event will be pushed.
  [in] | destination | The address to which the event will be sent.
  [out] | origin | The address from which the event is sent.
  [out] | event | The structure containing the event.
  [in] | soft | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when the destination address has not joined the event queue.
  FAILURE | interruption 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] | svm | The SVM pointer passed as first argument of the callback function.
  [in,out] | event_queue | The event queue on which the event will be pushed.
  [in] | destination | The address to which the event will be sent.
  [in] | origin | The address from which the event is sent.
  [in] | event | The 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

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when the origin or the destination address has not joined the event queue.

See also
  svm_structure_new