lsst::base Namespace Reference

Namespaces
namespace	version

Classes
class	LibraryException
	Unable to load library. More...
class	ModuleImporter
	Base class that defines an interface for importing Python modules. More...
class	NoThreadsException
	No threading library is available. More...
class	PythonModuleImporter

Functions
std::string	libraryExtension ()
	Return filename extension for libraries. More...
std::string	getLibraryFilename (std::string const &name)
	Get filename for library. More...
bool	canLoadLibrary (std::string const &libName)
	Return whether we can load a library. More...
template<typename T >
T *	loadSymbol (std::string const &libName, std::string const &symName)
	Load a symbol from a dynamic library. More...
bool	haveThreads ()
	Are threaded packages available? More...
void	setNumThreads (unsigned int numThreads)
	Set number of threads to use. More...
unsigned int	getNumThreads ()
	Get maximum number of threads we might use. More...
bool	disableImplicitThreading ()
	Disable threading that has not been set explicitly. More...
void	installPythonModuleImporter ()
	PYBIND11_MODULE (cppimport, mod)
	PYBIND11_MODULE (threads, mod)

Variables
bool const	haveOpenBlas = loadOpenBlas()
	Is OpenBLAS available? More...
bool const	haveMkl = loadMkl()
	Is MKL available? More...
std::string const	allowEnvvar = "LSST_ALLOW_IMPLICIT_THREADS"
	Environment variable to allow implicit threading. More...

Function Documentation

canLoadLibrary()

bool lsst::base::canLoadLibrary

(

std::string const &

libName

)

Return whether we can load a library.

The proper filename extension will be added to the library name unless one is specified.

Parameters

libName

Library name

Definition at line 37 of file library.cc.

{
    return dlopen(getLibraryFilename(libName).c_str(), RTLD_NOW | RTLD_GLOBAL);
}

disableImplicitThreading()

bool lsst::base::disableImplicitThreading

(

)

Disable threading that has not been set explicitly.

Some threaded packages implicitly use multiple threads if the user doesn't explicitly state the number of desired threads. However, this can interfere with operations that are parallelised at a higher level. This function will disable threading unless the user has explicitly specified the number of desired threads through environment variables.

This behavior may be disabled by setting the environment variable specified by allowEnvvar.

This is principally intended for Linux machines (we explicitly load .so dynamic libraries); MacOS has its own way of doing threading (Grand Central Dispatch) that throttles threads to avoid overwhelming the machine.

@ return whether we disabled threading

Definition at line 132 of file threads.cc.

{
    if (std::getenv(allowEnvvar.c_str())) {
        return false; // The user knows what he's doing; no intervention performed
    }
 
    bool intervened = false;            // Did we intervene on behalf of the user?
    if (haveOpenBlas) {
        intervened |= disableImplicitThreadingImpl(
            "OpenBLAS",
            {"OPENBLAS_NUM_THREADS", "GOTO_NUM_THREADS", "OMP_NUM_THREADS"},
            getOpenBlasThreads,
            setOpenBlasThreads
            );
    }
    if (haveMkl) {
        intervened |= disableImplicitThreadingImpl(
            "MKL",
            {"MKL_NUM_THREADS", "MKL_DOMAIN_NUM_THREADS", "OMP_NUM_THREADS"},
            getMklThreads,
            setMklThreads
            );
    }
    return intervened;
}

getLibraryFilename()

std::string lsst::base::getLibraryFilename

(

std::string const &

name

)

Get filename for library.

We'll add the typical filename extension for the platform unless the user specifies a ".so" or ".dylib" extension.

Definition at line 27 of file library.cc.

{
    if (endsWith(name, ".so") || endsWith(name, ".dylib")) {
        // User asked for a library with a certain extension, so give it to them
        return name;
    }
    return name + libraryExtension();
}

getNumThreads()

unsigned int lsst::base::getNumThreads

(

)

Get maximum number of threads we might use.

Returns the maximum value of the number of threads being used by the threading libraries that are available.

Definition at line 120 of file threads.cc.

{
    unsigned int numThreads = 0;
    if (haveOpenBlas) {
        numThreads = std::max(numThreads, static_cast<unsigned int>(getOpenBlasThreads()));
    }
    if (haveMkl) {
        numThreads = std::max(numThreads, static_cast<unsigned int>(getMklThreads()));
    }
    return numThreads;
}

haveThreads()

bool lsst::base::haveThreads

(

)

Are threaded packages available?

Definition at line 26 of file threads.h.

{ return haveOpenBlas || haveMkl; }

installPythonModuleImporter()

void lsst::base::installPythonModuleImporter

(

)

Definition at line 60 of file cppimport.cc.

{ ModuleImporter::install(PythonModuleImporter::get()); }

libraryExtension()

std::string lsst::base::libraryExtension

(

)

Return filename extension for libraries.

Typically ".so" for Linux and ".dylib" for Mac.

Definition at line 17 of file library.cc.

{
#ifdef __APPLE__
    return ".dylib";
#else
    return ".so";
#endif
}

loadSymbol()

template<typename T >

T * lsst::base::loadSymbol	(	std::string const &	libName,
		std::string const &	symName
	)

Load a symbol from a dynamic library.

The proper filename extension will be added to the library name unless one is specified.

No mangling is performed on the symbol name.

Parameters

libName	Library name (NOT including ".so" or ".dylib")
symName	Symbol name

Definition at line 51 of file library.h.

{
    void* lib = dlopen(getLibraryFilename(libName).c_str(), RTLD_NOW | RTLD_GLOBAL | RTLD_DEEPBIND);
    if (!lib) {
        throw LibraryException(libName);
    }
 
    T* sym;
    (void*&)sym = dlsym(lib, symName.c_str());
    if (!sym) {
        throw LibraryException(libName, symName);
    }
    return sym;
}

PYBIND11_MODULE() [1/2]

lsst::base::PYBIND11_MODULE	(	cppimport	,
		mod
	)

Definition at line 62 of file cppimport.cc.

                                {
    lsst::base::installPythonModuleImporter();
}

PYBIND11_MODULE() [2/2]

lsst::base::PYBIND11_MODULE	(	threads	,
		mod
	)

Definition at line 32 of file threads.cc.

                              {
    mod.def("haveThreads", &lsst::base::haveThreads);
    mod.def("setNumThreads", &lsst::base::setNumThreads);
    mod.def("getNumThreads", &lsst::base::getNumThreads);
    mod.def("disableImplicitThreading", &lsst::base::disableImplicitThreading);
}

setNumThreads()

void lsst::base::setNumThreads

(

unsigned int

numThreads

)

Set number of threads to use.

Exceptions

NoThreadsException

if no threading library is available

Definition at line 107 of file threads.cc.

{
    if (!haveOpenBlas && !haveMkl && numThreads != 0 && numThreads != 1) {
        throw NoThreadsException();
    }
    if (haveOpenBlas) {
        setOpenBlasThreads(numThreads);
    }
    if (haveMkl) {
        setMklThreads(numThreads);
    }
}

Variable Documentation

allowEnvvar

std::string const lsst::base::allowEnvvar = "LSST_ALLOW_IMPLICIT_THREADS"

Environment variable to allow implicit threading.

Used by disableImplicitThreading.

Definition at line 16 of file threads.h.

haveMkl

bool const lsst::base::haveMkl = loadMkl()

extern

Is MKL available?

Definition at line 105 of file threads.cc.

haveOpenBlas

bool const lsst::base::haveOpenBlas = loadOpenBlas()

extern

Is OpenBLAS available?

Definition at line 104 of file threads.cc.