NAME

OpenMP::Simple - Provides some DWIM helpers for using OpenMP via Inline::C.

SYNOPSIS

use OpenMP::Simple;
use OpenMP::Environment;

use Inline (
    C                 => 'DATA',
    with              => qw/OpenMP::Simple/,
);

DESCRIPTION

This module attempts to ease the transition for those more familiar with programming C with OpenMP than they are with Perl or using Inline::C within their Perl programs. It build upon the configuration information that is provided for by Alien::OpenMP, and appends to the AUTO_INCLUDE literal lines of C code that defines useful macros and data conversion functions (Perl to C, C to Perl).

In addition to helping to deal with getting data structures that are very common in the computational domains into and out of these Inline::C'd routines that leverage OpenMP, this module provides macros that are designed to provide behavior that is assumed to work when executing a binary that has been compiled with OpenMP support, such as the awareness of the current state of the OMP_NUM_THREADS environmental variable.

PROVIDED MACROS

Updating Runtime with Environmental Variables

When Inline::C compiles and loads these shared libraries once, when the script is first loaded. At this time, the OpenMP runtime inspects %ENV; but the environment is not automatically updated as whenever the runtime interfaces to the compiled library is used. The following macros offer a very concise and convenient way to update in the runtime based on the values of the respective environmental variables. They are designed with the use of OpenMP::Environment in mind, which provides an OpenMP specific OOP interface to getting and setting these variables. Nearly all of them correspond to a way to set them in the OpenMP runtime (provided by the compiler's implementation, e.g., omp.h).

All MACROS have at least 1 test. Please those in the Github repository to get an idea of how to use OpenMP::Simple's macros with OpenMP::Environment.

PerlOMP_ENV_SET_NUM_THREADS

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_NUM_THREADS}, which is managed via OpenMP::Environment->omp_num_threads[int numThreads]);.

PerlOMP_ENV_SET_DEFAULT_DEVICE

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_DEFAULT_DEVICE}, which is managed via OpenMP::Environment->omp_default_device([int deviceNo]);.

PerlOMP_ENV_SET_MAX_ACTIVE_LEVELS

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_MAX_ACTIVE_LEVELS}, which is managed via OpenMP::Environment->omp_max_active_levels([int maxLevel]);.

PerlOMP_ENV_SET_DYNAMIC

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_DYNAMIC}, which is managed via OpenMP::Environment->omp_dynamic(['true'|'false']);.

PerlOMP_ENV_SET_NESTED

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_NESTED}, which is managed via OpenMP::Environment->omp_nested(['true'|'false']);.

PerlOMP_ENV_SET_SCHEDULE

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_SCHEDULE}, which is managed via OpenMP::Environment->omp_schedule(...);.

Note: The schedule syntax is of the form schedule[;chunkSize].

PerlOMP_ENV_SET_TEAMS_THREAD_LIMIT

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_TEAMS_THREAD_LIMIT}, which is managed via OpenMP::Environment->omp_([int limit]);.

Note: Not supported until GCC 12.3.0

PerlOMP_ENV_SET_NUM_TEAMS

Updates the OpenMP runtime with the value of the environmental variable, $ENV{OMP_NUM_TEAMS}, which is managed via OpenMP::Environment->omp_([int num]);.

Note: Not supported until GCC 12.3.0

PerlOMP_RET_ARRAY_REF_ret

(may not be needed) - creates a new AV* and sets it mortal (doesn't survive outside of the current scope). Used when wanting to return an array reference that's been populated via av_push.

PROVIDED PERL TO C CONVERSION FUNCTIONS

PerlOMP_2D_AoA_TO_FLOAT_ARRAY_2D(AoA, num_nodes, dims, nodes)

Used to extract the contents of a 2D rectangular Perl array reference that has been used to represent a 2D matrix.

float nodes[num_nodes][dims];
PerlOMP_2D_AoA_TO_FLOAT_ARRAY_2D(AoA, num_nodes, dims, nodes);

SEE ALSO

This is a module that aims at making it easier to bootstrap Perl+OpenMP programs. It is designed to work together with OpenMP::Environment.

This module heavily favors the GOMP implementation of the OpenMP specification within gcc. In fact, it has not been tested with any other implementations.

https://gcc.gnu.org/onlinedocs/libgomp/index.html

Please also see the rperl project for a glimpse into the potential future of Perl+OpenMP, particularly in regards to thread-safe data structures.

https://www.rperl.org

AUTHOR

Oodler 577 <oodler@cpane.org>

LICENSE & COPYRIGHT

Same as Perl.