User Manual: Code: Core.pm

From FLUX

(back to the User Manual or the code section)

Flux::Core contains nothing of interest to the casual user. It is used to link the C libraries to the running Perl, and declares no methods nor any variables of interest to the user.

Internals

The FLUX C libraries are stored in a static library, libflux.a, that gets put into /usr/local/lib. The PerlXS bridging mechanism generates dynamically linkable files for each Perl module it compiles, and any static libraries (including libflux.a) are linked separately into each module that references it. That is wasteful -- FLUX's C libraries compile to over 400k, so five copies (one for each module) cost 2MB -- and it causes problems because some of the switchable functions in the library are implemented with function pointers. If multiple copies of the library exist in memory, then the function pointers don't have definite values (even if the different copies do exactly the same thing).

FLUX avoids this problem with a simple form of dynamic linker: a "core structure" that serves as a kind of patch panel into the C library. The only module that directly references the FLUX C library is Flux::Core, which exists only to load the library into memory and generate a pointer to the patch panel. Other modules include a snippet of code in their BOOT sections, to locate the patch panel in the Flux::Core module and load its location into a global structure pointer.

This is the same mechanism that is used by PDL, so each .xs file contains two nearly identical snippets at the bottom, to load the PDL core and the FLUX core.

Load sequence

When you use Flux, the first module that is actually loaded is Flux::Core, which links the C library into the running Perl. The BOOT section of Core.xs loads the value of each symbol in the FLUX library into a corresponding field in a master structure of type FluxCore. (The structure type is declared in fluxperl.h). A pointer to that master structure gets stored in a global Perl scalar ($Flux::Core::FLUX), where other modules can access it.

All other modules that call the C libraries retrieve the value of $Flux::Core::FLUX and stuff it into a structure pointer called FLUX. (This happens in the BOOT section of each .XS file) Library function calls and global variables are then accessed through constructs like FLUX->name, rather than just name.

If you add a new function or variable to the patch panel, you must increment its version number (to force a recompile of any modules that use it); that is declared in a #define in fluxperl.h.

Perl-Object / C-Structure Access

In addition to generating the FLUX core structure, Core.xs declares four important internal utility subroutines that are useful throughout the Perl/XS modules:

• SvFluxPtr(), which accepts a Perl object (as a C "SV *") and returns a pointer to the underlying structure (keeping track of the number of such structures in the WORLD's refct field);
• SvFluxLabel(), which does the same thing but returns the unique integer label of that structure;
• new_sv_from_ptr(), which constructs (and returns) a Perl FLUX object from a FLUX structure pointer, incrementing the refct for the WORLD to keep the Universe in balance; and
• destroy_sv(), which destroys a FLUX Perl structure and decrements the WORLD's refct. (in the Perl internals, structures maintain a reference count; if the count drops to zero, the structure is de-allocated. The refct field in the WORLD C structure keeps track of that.)