The library infrastructure module

struct dip::LibraryInformation

#include "diplib.h"

Holds information about the DIPlib binary.

Information in this structure can be used to display library information to the user (e.g. in a splash screen). It also contains information that can be used to determine at run time the properties of the DIPlib library that the application links to. Refer to dip::libraryInformation.

The string type starts either with “Release” or “Debug”, indicating the whether the library was compiled with optimizations enabled and no debug information (release) or without optimizations and with debug information (debug). Next it lists a series of compile-time options, separated by comma. The options are:

• “with OpenMP”: indicates multithreading is built in.
• “recording stack traces”: indicates that exceptions report a stack trace, rather than only show the function that threw it.
• “asserts enabled”: indicates additional run-time tests for consistency are executed.
• “Unicode support”: indicates e.g. units are output using Unicode.
• “ICS support”: indicates ICS file reading and writing is available.
• “TIFF support”: indicates TIFF file reading and writing is available.
• “JPEG support”: indicates JPEG file reading and writing is available.
• “PNG support”: indicates PNG file reading and writing is available.

void dip::SetNumberOfThreads(dip::uint nThreads)

#include "diplib/multithreading.h"

Sets the maximum number of threads to be using in computations.

The default maximum number of threads is given by the OMP_NUM_THREADS environment variable if set, or the number of CPU cores otherwise.

Note that parallelized algorithms only spawn multiple threads for the computation if the amount of work to be done is large enough to compensate for the overhead of spawning threads.

If nThreads is 1, disables multithreading within DIPlib. Usually it is more beneficial to manage multithreading at a higher level, for example by processing multiple images at the same time. If you do so, set nThreads to 1. Furthermore, it seems that calling multithreaded DIPlib functions from within an OpenMP parallel section doesn’t work, so within an OpenMP parallel section you should always set nThreads to 1.

If nThreads is 0, resets the maximum number of threads to the default value.

Note that this number is thread-local, meaning it only applies to the current thread from which this function is called. For every newly spawned thread, the maximum number of threads is the default as described above, not the value manually set prior to spawning the thread.

If DIPlib was compiled without OpenMP support, this function does nothing.

dip::uint dip::GetNumberOfThreads()

#include "diplib/multithreading.h"

Gets the maximum number of threads that can be used in computations.

Returns the value given in the last call to dip::SetNumberOfThreads within the current thread, or the default maximum value if that function was never called within the current thread.

If DIPlib was compiled without OpenMP support, this function always returns 1.

dip::LibraryInformation const dip::libraryInformation

#include "diplib.h"

Constant that holds information about the DIPlib binary.

#define DIP_EXPORT

#include "diplib.h"

Indicates that the function or class is exported from the shared/dynamic-load library.

#define DIP_NO_EXPORT

#include "diplib.h"

Indicates that the function or class is not exported from the shared/dynamic-load library.

#define DIP_CLASS_EXPORT

#include "diplib.h"

Specifically for classes in a inheritance hierarchy and that must be passed across the executable/shared library interface.

Equal to DIP_NO_EXPORT on Windows and DIP_EXPORT elsewhere.

On Linux and other Unix-like systems, classes in a hierarchy, as well as classes thrown as exceptions, must be exported from the shared library if they are to be used across the interface between the library and whatever is using the library. This is the only way that the run-time linker is able to merge the virtual function tables, and identify the type of the thrown object.

However, on Windows, trying to export a class derived from a class in the standard library (such as std::exception), or trying to export a class that contains members of a non-exported class (such as a dip::String, a.k.a. std::string), causes compiler warnings. It seems that currently it is considered best practice to not export such classes. The Windows run-time linker always maps local classes to those in the shared library, even when they are not exported.

#define DIP_NODISCARD

#include "diplib.h"

If your compiler supports it, adds [[nodiscard]] to a function definition.

[[nodiscard]] will produce a compile-time warning if the function return value is discarded. This should pick up some programming errors, especially in cases where a different overload is picked by the compiler than expected by the programmer. For example:

dip::Mean( in, {}, out ); // OK, picks main function
out = dip::Mean( in );    // OK, picks alternate overload
dip::Mean( in, out );     // warns, picks alternate overload and output is discarded

The third line will warn because the compiler picks the dip::Mean( in, mask ) overload that returns the result image, rather than the intended main function dip::Mean( in, mask, out ) that puts the result in the existing out image.