/ 
OpenMP-Simple-0.0.6
River stage zero No dependents
/ OpenMP::Simple

NAME

OpenMP::Simple - Provides some DWIM C functions and MACROs, built on top of Alien::OpenMP.

SYNOPSIS

use OpenMP::Simple;      # uses Alien::OpenMP, provides helpful C MACROs
use OpenMP::Environment; # setters/getters for important OpenMP environmental variables 

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

Note: while not experimental per se, this module is still in a very fluid state. It is actively being used as the basis for real world codes. As more experience and intuition is gained by using it, this interface will only improve. Feedback is very valuable, so please reach out to "OODLER <oodler@cpan.org>" or visit the Perl+OpenMP Github repository, https://github.com/Perl-OpenMP.

DESCRIPTION

OpenMP::Simple is meant to work together with OpenMP::Environment in a way that provides the same runtime control experience that OpenMP's environmental variables provides.

Contained here is essentially a set of macros and Inline::C defined C functions that make it easier for Perl programs to interface basic Perl structures more directly with Inline::C functions for use with OpenMP It also containes macros that emulate the access of OpenMP programs to %ENV at program start up, and through this module, during runtime.

Note: normal OpenMP programs do not re-sample %ENV during runtime, but OpenMP::Simple provides macros to do just that; so this module provides an additional level of control that so that OpenMP::Environment may be used effectively during the running of a Perl program that contains Inline::C functions with OpenMP inside of them.

As a reminder, the OpenMP standard has several aspects that work in concert to make shared memory programming (with NUMA/SMP threads) more accessible. These aspects may be summarized as the following:

1. a runtime and library of runtime callable functions

that may be used to programatically affect execution and work distribution; here is where this module, OpenMP::Simple makes a contribution to extending the promise of OpenMP to Perl programmers.

2. a set of environmental variables (i.e., %ENV)

that can be used to control the OpenMP runtime; this aspect is where the OpenMP::Environment module comes into play.

3. work sharing constructs used to implicitly share memory and executions among a series of threads; these are implemented directly into the C code, and is also where most of the hard work for anyone (including Perl programmers) exists. I.e., making OpenMP more perlish. It also may including in the future, using OpenMP inside of the perl interpreter itself; but this is the domain of core Perl maintainers and experts in language semantics. No attempt has been made so far to address this large and very fruitful area of exploration.

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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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_UPDATE_WITH_ENV__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

Note: Work is currently focused on finding the true limits of the Perl C API. It is likely that in a lot of cases, elements in Perl Arrays (AV) and Perl Hashes (HV) maybe accessed safely without first transferring the entire data structures into its pure C equivalent.

PerlOMP_2D_AoA_TO_2D_FLOAT_ARRAY(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_2D_FLOAT_ARRAY(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

Brett Estrade <oodler@cpan.org>

LICENSE & COPYRIGHT

Same as Perl.