starpu-max/doc/doxygen/chapters/api/interoperability.doxy

/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2018                                     Inria
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */

/*! \defgroup API_Interop_Support Interoperability Support

\brief This section describes the interface supplied by StarPU to interoperate with other runtime systems.

\enum e_starpurm_drs_ret
\ingroup API_Interop_Support
StarPU Resource Manager return type.
\var starpurm_drs_ret::starpurm_DRS_SUCCESS
  Dynamic resource sharing operation succeeded.
\var starpurm_drs_ret::starpurm_DRS_DISABLD
  Dynamic resource sharing is disabled.
\var starpurm_drs_ret::starpurm_DRS_PERM
  Dynamic resource sharing operation is not authorized or implemented.
\var starpurm_drs_ret::starpurm_DRS_EINVAL
  Dynamic resource sharing operation has been called with one or more invalid parameters.

@name Initialisation
\ingroup API_Interop_Support

\fn void starpurm_initialize(void)
\ingroup API_Interop_Support
Initialize StarPU and the StarPU-RM resource management module. The starpu_init() function should not have been called before the call to starpurm_initialize(). The starpurm_initialize() function will take care of this

\fn void starpurm_shutdown(void)
\ingroup API_Interop_Support
Shutdown StarPU-RM and StarPU. The starpu_shutdown() function should not be called before. The starpurm_shutdown() function will take care of this.


@name Spawn
\ingroup API_Interop_Support

\fn void starpurm_spawn_kernel_on_cpus(void *data, void(*f)(void *), void *args, hwloc_cpuset_t cpuset)
\ingroup API_Interop_Support
Allocate a temporary context spanning the units selected in the cpuset bitmap,
set it as the default context for the current thread, and call user function \p f.
Upon the return of user function \p f, the temporary context is freed and the previous
default context for the current thread is restored.

\fn void starpurm_spawn_kernel_on_cpus_callback(void *data, void(*f)(void *), void *args, hwloc_cpuset_t cpuset, void(*cb_f)(void *), void *cb_args)
\ingroup API_Interop_Support
Spawn a POSIX thread and returns immediately. The thread spawned will allocate
a temporary context spanning the units selected in the cpuset bitmap, set it as
the default context for the current thread, and call user function \p f. Upon
the return of user function \p f, the temporary context will be freed and the
previous default context for the current thread restored. A user specified callback \p cb_f
will be called just before the termination of the thread.

@name DynamicResourceSharing
\ingroup API_Interop_Support

\fn starpurm_drs_ret_t starpurm_set_drs_enable(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Turn-on dynamic resource sharing support.

\fn starpurm_drs_ret_t starpurm_set_drs_disable(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Turn-off dynamic resource sharing support.

\fn int starpurm_drs_enabled_p(void)
\ingroup API_Interop_Support
Return the state of the dynamic resource sharing support (\p =!0 enabled, \p =0 disabled).

\fn starpurm_drs_ret_t starpurm_set_max_parallelism(starpurm_drs_desc_t *spd, int max)
\ingroup API_Interop_Support
Set the maximum number of CPU computing units available for StarPU computations
to \p max. This number cannot exceed the maximum number of StarPU's CPU worker
allocated at start-up time.

\fn starpurm_drs_ret_t starpurm_assign_cpu_to_starpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to execute tasks on worker
corresponding to logical unit \p cpuid. If StarPU does not have a worker
thread initialized for logical unit \p cpuid, do nothing.

\fn starpurm_drs_ret_t starpurm_assign_cpus_to_starpu(starpurm_drs_desc_t *spd, int ncpus)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to execute tasks on \p ncpus
more workers, up to the number of StarPU worker threads initialized.

\fn starpurm_drs_ret_t starpurm_assign_cpu_mask_to_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to execute tasks on the
additional logical units selected in \p mask. Logical units of \p mask for which no
StarPU worker is initialized are silently ignored.

\fn starpurm_drs_ret_t starpurm_assign_all_cpus_to_starpu(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Set StarPU's default scheduling context to execute tasks on all
available logical units for which a StarPU worker has been initialized.

\fn starpurm_drs_ret_t starpurm_withdraw_cpu_from_starpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context so as to not execute tasks on worker
corresponding to logical unit \p cpuid. If StarPU does not have a worker
thread initialized for logical unit \p cpuid, do nothing.

\fn starpurm_drs_ret_t starpurm_withdraw_cpus_from_starpu(starpurm_drs_desc_t *spd, int ncpus)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context to execute tasks on \p ncpus
less workers.

\fn starpurm_drs_ret_t starpurm_withdraw_cpu_mask_from_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context so as to not execute tasks on the
logical units selected in \p mask. Logical units of \p mask for which no
StarPU worker is initialized are silently ignored.

\fn starpurm_drs_ret_t starpurm_withdraw_all_cpus_from_starpu(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context so as to remove all logical units.

\fn starpurm_drs_ret_t starpurm_lend(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Synonym for starpurm_assign_all_cpus_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_cpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Synonym for starpurm_assign_cpu_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_cpus(starpurm_drs_desc_t *spd, int ncpus)
\ingroup API_Interop_Support
Synonym for starpurm_assign_cpus_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_assign_cpu_mask_to_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_all_cpus_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_cpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpu_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_cpus(starpurm_drs_desc_t *spd, int ncpus)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpus_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpu_mask_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_all_cpus_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_cpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpu_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_cpus(starpurm_drs_desc_t *spd, int ncpus)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpus_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_cpu_mask_from_starpu().

\fn starpurm_drs_ret_t starpurm_return_all(starpurm_drs_desc_t *spd)
\ingroup API_Interop_Support
Synonym for starpurm_assign_all_cpus_to_starpu().

\fn starpurm_drs_ret_t starpurm_return_cpu(starpurm_drs_desc_t *spd, int cpuid)
\ingroup API_Interop_Support
Synonym for starpurm_assign_cpu_to_starpu().

@name Devices
\ingroup API_Interop_Support

\fn int starpurm_get_device_type_id(const char *type_str)
\ingroup API_Interop_Support
Return the device type ID constant associated to the device type name.
Valid names for \p type_str are:
- \c "cpu": regular CPU unit;
- \c "opencl": OpenCL device unit;
- \c "cuda": nVidia CUDA device unit;
- \c "mic": Intel KNC type device unit.

\fn const char *starpurm_get_device_type_name(int type_id)
\ingroup API_Interop_Support
Return the device type name associated to the device type ID constant.

\fn int starpurm_get_nb_devices_by_type(int type_id)
\ingroup API_Interop_Support
Return the number of initialized StarPU worker for the device type \p type_id.

\fn int starpurm_get_device_id(int type_id, int device_rank)
\ingroup API_Interop_Support
Return the unique ID assigned to the \p device_rank nth device of type
\p type_id.

\fn starpurm_drs_ret_t starpurm_assign_device_to_starpu(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to use \p unit_rank nth
device of type \p type_id.

\fn starpurm_drs_ret_t starpurm_assign_devices_to_starpu(starpurm_drs_desc_t *spd, int type_id, int ndevices)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to use \p ndevices more
devices of type \p type_id, up to the number of StarPU workers
initialized for such device type.

\fn starpurm_drs_ret_t starpurm_assign_device_mask_to_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to use additional devices as
designated by their corresponding StarPU worker thread(s) CPU-set \p mask.

\fn starpurm_drs_ret_t starpurm_assign_all_devices_to_starpu(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Extend StarPU's default scheduling context to use all devices of type \p
type_id for which it has a worker thread initialized.

\fn starpurm_drs_ret_t starpurm_withdraw_device_from_starpu(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context to not use \p unit_rank nth
device of type \p type_id.

\fn starpurm_drs_ret_t starpurm_withdraw_devices_from_starpu(starpurm_drs_desc_t *spd, int type_id, int ndevices)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context to use \p ndevices less
devices of type \p type_id.

\fn starpurm_drs_ret_t starpurm_withdraw_device_mask_from_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context to not use devices
designated by their corresponding StarPU worker thread(s) CPU-set \p mask.

\fn starpurm_drs_ret_t starpurm_withdraw_all_devices_from_starpu(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Shrink StarPU's default scheduling context to use no devices of type \p
type_id.

\fn starpurm_drs_ret_t starpurm_lend_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Synonym for starpurm_assign_device_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
\ingroup API_Interop_Support
Synonym for starpurm_assign_devices_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_assign_device_mask_to_starpu().

\fn starpurm_drs_ret_t starpurm_lend_all_devices(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Synonym for starpurm_assign_all_devices_to_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_device_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_devices_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_device_mask_from_starpu().

\fn starpurm_drs_ret_t starpurm_reclaim_all_devices(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_all_devices_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_device_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_devices_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_device_mask_from_starpu().

\fn starpurm_drs_ret_t starpurm_acquire_all_devices(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Synonym for starpurm_withdraw_all_devices_from_starpu().

\fn starpurm_drs_ret_t starpurm_return_all_devices(starpurm_drs_desc_t *spd, int type_id)
\ingroup API_Interop_Support
Synonym for starpurm_assign_all_devices_to_starpu().

\fn starpurm_drs_ret_t starpurm_return_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
\ingroup API_Interop_Support
Synonym for starpurm_assign_device_to_starpu().

@name CpusetsQueries
\ingroup API_Interop_Support

\fn hwloc_cpuset_t starpurm_get_device_worker_cpuset(int type_id, int unit_rank)
\ingroup API_Interop_Support
Return the CPU-set of the StarPU worker associated to the \p unit_rank
nth unit of type \p type_id.

\fn hwloc_cpuset_t starpurm_get_global_cpuset(void)
\ingroup API_Interop_Support
Return the cumulated CPU-set of all StarPU worker threads.

\fn hwloc_cpuset_t starpurm_get_selected_cpuset(void)
\ingroup API_Interop_Support
Return the CPU-set of the StarPU worker threads currently selected in
the default StarPU's scheduling context.

\fn hwloc_cpuset_t starpurm_get_all_cpu_workers_cpuset(void)
\ingroup API_Interop_Support
Return the cumulated CPU-set of all CPU StarPU worker threads.

\fn hwloc_cpuset_t starpurm_get_all_device_workers_cpuset(void)
\ingroup API_Interop_Support
Return the cumulated CPU-set of all "non-CPU" StarPU worker threads.

\fn hwloc_cpuset_t starpurm_get_all_device_workers_cpuset_by_type(int typeid)
\ingroup API_Interop_Support
Return the cumulated CPU-set of all StarPU worker threads for devices of
type \p typeid.

*/