API description
***************

This section describes the support of OmpSs through direct library calls to the
runtime system. This services will allow to configure, check configuration or
perform some functionality (e.g., lock services) when using the OmpSs
programming model.

Thread count and identifier
===========================

Setting or getting the number of threads. In OmpSs the
``omp_get_max_threads()`` is equivalent to ``omp_get_num_threads()`` due there
is no explicit parallel region::

  void omp_set_num_threads(int num_threads);
  int  omp_get_num_threads(void);
  int  omp_get_max_threads(void);

Getting the thread identifer::

  int  omp_get_thread_num(void);

Getting the number of CPUs availabe in the current execution::

  int  omp_get_num_procs(void);

Getting the Operating System limit of threads::

  int  omp_get_thread_limit(void);

Useful getters and setters*
==========================

.. NOT IN OMPSS
.. Setting or getting dynamic behaviour may change the number of threads between parallel regions::
.. 
..   void omp_set_dynamic(int dynamic_threads);
..   int  omp_get_dynamic(void);
.. 
.. Setting or getting nested behaviour may allow to create a parallel region within another parallel region::
.. 
..   void omp_set_nested(int nested);
..   int  omp_get_nested(void);

Setting or getting the ``schedule`` policy as the default policy for a ``loop``
construct (ie, ``for`` in C/C++ and ``do`` in Fortran). The routines also allow
to set a modifer (ie, a chunk size)::

  void omp_set_schedule(omp_sched_t kind, int modifier);
  void omp_get_schedule(omp_sched_t *kind, int *modifier);

Getting if the current task is in final mode (ie, the *final-expression* has evaluated to true)::

  int  omp_in_final(void);

.. NOT IN OMPSS
.. Getting if current region executes within a parallel region::
.. 
..   int  omp_in_parallel(void);



Using locks
===========

The following routines allow to initialize, destroy, set, unset and test an OmpSs lock::

  void omp_init_lock(omp_lock_t *lock);
  void omp_destroy_lock(omp_lock_t *lock);
  void omp_set_lock(omp_lock_t *lock);
  void omp_unset_lock(omp_lock_t *lock);
  int  omp_test_lock(omp_lock_t *lock);

Using nested locks
==================

The following routines allow to initialize, destroy, set, unset and test an OmpSs nested lock::

  void omp_init_nest_lock(omp_nest_lock_t *lock);
  void omp_destroy_nest_lock(omp_nest_lock_t *lock);
  void omp_set_nest_lock(omp_nest_lock_t *lock);
  void omp_unset_nest_lock(omp_nest_lock_t *lock);
  int  omp_test_nest_lock(omp_nest_lock_t *lock);

A set operation over a nested lock will proceed if the lock owner is the
current thread, and will block if is not the current thread.

Timing routines
===============

The following routines will get a time-stamp or tick-stamp based on the processor clock::

  double omp_get_wtime(void);
  double omp_get_wtick(void);


.. NOT YET DOCUMENTED
.. void omp_set_max_active_levels(int max_active_levels);
.. int  omp_get_max_active_levels(void);
.. int  omp_get_level(void);
.. int  omp_get_ancestor_thread_num(int level);
.. int  omp_get_team_size(int level);
.. int  omp_get_active_level(void);