Simple Virtual Machine A simple but flexible virtual machine

Functions
SVM process ownership
SVM processes

This module contains API functions to handle SVM process ownership. More...

## Functions
SVM_FUNCTION SVM_Process_Lock | svm_process_ownership_lock (const void *svm, const SVM_Process process)
| This function locks a process from the current process. More...
SVM_FUNCTION SVM_Process_Lock | svm_process_ownership_lock_critical (const void *svm)
| This function locks all other processes. More...
SVM_FUNCTION SVM_Boolean | svm_process_ownership_check (const void *svm, const SVM_Process process)
| This function checks whether the current process owns another process. More...
SVM_FUNCTION SVM_Boolean | svm_process_ownership_get_local (const void *svm, const SVM_Process process)
| This function locally takes ownership over another process. More...

## Detailed Description

This module contains API functions to handle SVM process ownership.

## Function Documentation

## ◆ svm_process_ownership_check()

SVM_FUNCTION SVM_Boolean svm_process_ownership_check | ( | const void * | svm,
|  | const SVM_Process | process
| ) |  |

This function checks whether the current process owns another process.

Parameters

  [in] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | process | The process ownership to check.

The current process owns another process when:

- Either the process is also the current process,
- Or a lock exists on the process from the current process.

Returns
  TRUE when the current process owns the process, FALSE otherwise.

Exceptions

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)

See also
  svm_process_ownership_lock
  svm_process_ownership_lock_critical
  svm_variable_delete

## ◆ svm_process_ownership_get_local()

SVM_FUNCTION SVM_Boolean svm_process_ownership_get_local | ( | const void * | svm,
|  | const SVM_Process | process
| ) |  |

This function locally takes ownership over another process.

Parameters

  [in] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | process | The process ownership to take locally.

The current process takes the ownership of the process until the end of the plugin callback.

Note
  If a lock is acquired, it is placed in an hidden local variable.

Returns
  TRUE when the current process succeeds to own the process, FALSE otherwise.

Exceptions

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when this API function is called outside a waiting instruction.

See also
  svm_process_ownership_lock
  svm_process_ownership_lock_critical
  svm_variable_delete

## ◆ svm_process_ownership_lock()

SVM_FUNCTION SVM_Process_Lock svm_process_ownership_lock | ( | const void * | svm,
|  | const SVM_Process | process
| ) |  |

This function locks a process from the current process.

Parameters

  [in] | svm | The SVM pointer passed as first argument of the callback function.
  [in] | process | The process to lock.

This function waits until the lock is acquired by the current process, unless an invalid lock attempt is performed.

The returned lock is a recursive lock: A lock attempt on a process already locked by the current process is accepted. All locks on the remote process have to be released to unlock the process.

Note
  To release the remote process, the returned lock has to be freed. See svm_variable_delete API function for more details.

A lock will never be acquired on:

- the current process,
- a dead process,
- a process creating a circular dead lock.

Returns
  The process lock if the process is owned by the current process, or a NULL pointer otherwise.

Warning
  If a NULL pointer is returned by this function, any action on the process can lead to an undefined behavior.

Usage example:

SVM_Process_Lock lock = svm_process_ownership_lock(svm,process);
if(svm_process_ownership_check(svm,process))
{
// current process owns process: operations on process allowed
}
if(lock)
{
// lock retains process execution
// lock variable can now be safely set as global and/or shared, and stored
// lock variable can be freed to release process execution
}
SVM_Process_Lock
SVM_TYPE typedef const void * SVM_Process_Lock
This type is used to represent the aquisition of a lock on a remote process.
Definition: svm.h:311
svm_process_ownership_lock
SVM_FUNCTION SVM_Process_Lock svm_process_ownership_lock(const void *svm, const SVM_Process process)
This function locks a process from the current process.
svm_process_ownership_check
SVM_FUNCTION SVM_Boolean svm_process_ownership_check(const void *svm, const SVM_Process process)
This function checks whether the current process owns another process.

Exceptions

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when this API function is called outside a waiting instruction.

See also
  svm_variable_delete
  svm_process_ownership_get_local
  svm_process_ownership_check

## ◆ svm_process_ownership_lock_critical()

SVM_FUNCTION SVM_Process_Lock svm_process_ownership_lock_critical | ( | const void * | svm | ) |

This function locks all other processes.

Parameters

  [in] | svm | The SVM pointer passed as first argument of the callback function.

This function locks all other processes for critical execution of code.

Warning
  Use this function with caution, as it can block the virtual machine. It is also avised to limit the lock scope to the instruction creating the lock.

Note
  To release the all processes, the returned lock has to be freed. See svm_variable_delete API function for more details.

Returns
  The process lock if all other processes are locked by us, or a NULL pointer otherwise.

Warning
  If a NULL pointer is returned by this function, any critical action performed can lead to an undefined behavior.

Exceptions

  FAILURE | interruption when a parameter is incorrect. (Please refer to the main description page of this API.)
  FAILURE | interruption when this API function is called outside a system waiting instruction.

See also
  svm_variable_delete
  svm_process_ownership_get_local
  svm_process_ownership_check