A formal description of a PixInsight module. More...

#include <MetaModule.h>

Inheritance diagram for pcl::MetaModule:

Public Member Functions
	MetaModule ()

	MetaModule (const MetaModule &)=delete

	~MetaModule () override

virtual void *	Allocate (size_type sz)

virtual String	Author () const

size_type	AvailablePhysicalMemory () const

virtual String	Company () const

virtual String	Copyright () const

virtual void	Deallocate (void *p)

virtual String	Description () const

Variant	EvaluateScript (const String &sourceCode, const IsoString &language=IsoString())

bool	GetPhysicalMemoryStatus (size_type &totalBytes, size_type &availableBytes) const

virtual void	GetReleaseDate (int &year, int &month, int &day) const

void	GetVersion (int &major, int &minor, int &release, int &build, IsoString &language, IsoString &status) const

bool	HasEntitlement (const IsoString &entitlement)

bool	IsInstalled () const

void	LoadResource (const String &filePath, const String &rootPath=String())

virtual IsoString	Name () const =0

virtual void	OnLoad ()

virtual void	OnUnload ()

MetaModule &	operator= (const MetaModule &)=delete

virtual String	OriginalFileName () const

float	PhysicalMemoryLoad () const

void	ProcessEvents (bool excludeUserInputEvents=false)

IsoString	ReadableVersion () const

virtual String	TradeMarks () const

virtual const char *	UniqueId () const

void	UnloadResource (const String &filePath, const String &rootPath=String())

virtual const char *	Version () const =0

Public Member Functions inherited from pcl::MetaObject
	MetaObject (const MetaObject &)=delete

	MetaObject (MetaObject &&x)=delete

	MetaObject (MetaObject *parent)

virtual	~MetaObject () noexcept(false)

size_type	Length () const

MetaObject &	operator= (const MetaObject &)=delete

MetaObject &	operator= (MetaObject &&x)=delete

const MetaObject *	operator[] (size_type i) const

MetaObject *	Parent ()

const MetaObject *	Parent () const

Additional Inherited Members
Public Types inherited from pcl::MetaObject
using	children_list = IndirectArray< MetaObject >

Detailed Description

MetaModule is the root element in the hierarchical structure of components that constitute every PixInsight module. This class provides a formal description of the basic functionality and properties of a module.

Every PixInsight module must define a unique subclass of MetaModule. That subclass, besides describing the module, will be the primary interface between all module components (processes, file formats and interfaces) and the PixInsight core application.

In any PixInsight module, there exists a unique instance of a derived class of MetaModule, accessible as a global pointer variable declared in the pcl namespace, namely:

namespace pcl
{
   extern MetaModule* Module;
} // pcl

The entire tree of existing module components can always be accessed by using the MetaObject::operator[]( size_type ) operator function recursively, starting from the Module global variable.

See also: MetaObject, MetaProcess, MetaParameter, MetaFileFormat

Definition at line 101 of file MetaModule.h.

Constructor & Destructor Documentation

◆ MetaModule() [1/2]

pcl::MetaModule::MetaModule ( )

Constructs a MetaModule object.

◆ ~MetaModule()

pcl::MetaModule::~MetaModule ( )

override

Destroys a MetaModule object and all of its child module components.

This function effectively destroys all existing module components by indirect recursion of MetaObject::~MetaObject().

◆ MetaModule() [2/2]

pcl::MetaModule::MetaModule ( const MetaModule & )

delete

Copy constructor. This constructor is disabled because MetaModule represents unique server-side objects.

Member Function Documentation

◆ Allocate()

virtual void* pcl::MetaModule::Allocate ( size_type sz )

inlinevirtual

Module allocation routine. Allocates a contiguous block of sz bytes, and returns its starting address.

This routine is called by PCL internal code, and indirectly by the PixInsight core application.

The default implementation simply calls ::operator new( sz ) to allocate a block of the specified size.

You usually should not need to reimplement this function, unless you want to implement a special memory management strategy for your module.

See also: Deallocate()

Definition at line 446 of file MetaModule.h.

◆ Author()

virtual String pcl::MetaModule::Author ( ) const

inlinevirtual

Returns the name of the author or authors of this module.

To specify multiple author names, separate them with commas.

Note: Reimplementing this function is optional, but advisable.

Definition at line 303 of file MetaModule.h.

◆ AvailablePhysicalMemory()

size_type pcl::MetaModule::AvailablePhysicalMemory ( ) const

inline

Returns an estimate of how much free memory is currently available.

This function returns the amount of memory in bytes that can be allocated by the caller without pushing the system into swap, taking into account memory being used for file caches that can be reclaimed. The current platform-dependent implementation returns accurate values on supported versions of FreeBSD, Linux, macOS, and Windows.

The returned value is zero in the event of error. In theory this can only happen on Linux if /proc/meminfo cannot be accessed, which should never happen on a healthy system under normal working conditions.

Definition at line 403 of file MetaModule.h.

References GetPhysicalMemoryStatus().

◆ Company()

virtual String pcl::MetaModule::Company ( ) const

inlinevirtual

Returns the name of the software company responsible for the development of this module.

Please don't advertise your company here. A module returning something like "MySoftwareCompany - Advanced Imaging Solutions for the Serious Imager" wouldn't be certified.

Note: Reimplementing this function is optional, but advisable.

Definition at line 291 of file MetaModule.h.

◆ Copyright()

virtual String pcl::MetaModule::Copyright ( ) const

inlinevirtual

Provides copyright information for this module.

Note: Reimplementing this function is optional, but advisable.

Definition at line 316 of file MetaModule.h.

◆ Deallocate()

virtual void pcl::MetaModule::Deallocate ( void * p )

inlinevirtual

Module deallocation routine. Deallocates a previously allocated contiguous block of memory starting at address p.

This routine is called by PCL internal code, and indirectly by the PixInsight core application.

The default implementation simply calls ::operator delete( p ) to free the specified block.

You usually should not need to reimplement this function, unless you want to implement a special memory management strategy for your module.

See also: Allocate()

Definition at line 467 of file MetaModule.h.

◆ Description()

virtual String pcl::MetaModule::Description ( ) const

inlinevirtual

Provides a brief description of this module.

This function is not intended to give a thorough description, but just a succinct sentence to quickly identify this module and its contents.

Example of good module description: "MyFancyCrop Process Module".

Example of bad module description: "This module implements MyFancyCrop: A high-performance process to crop and rotate images arbitrarily.".

Note: Reimplementing this function in a derived class is optional. However, this function should be reimplemented by all modules, to provide meaningful information to the users during module installation procedures.

Definition at line 276 of file MetaModule.h.

◆ EvaluateScript()

Variant pcl::MetaModule::EvaluateScript	(	const String &	sourceCode,
		const IsoString &	language = `IsoString()`
	)

Executes a script in the platform's core scripting engine.

Parameters

sourceCode	A string containing valid source code in the specified language.
language	The name of a supported scripting language. Currently only the JavaScript language is supported by this function. JavaScript is assumed if this string is either empty or equal to "JavaScript".

Returns the result value of the executed script. The result value is the value of the last executed expression statement in the script that is not in a function definition.

The script will be executed in the core JavaScript Runtime (PJSR). All PJSR resources are available.

If the script cannot be evaluated, for example because it has syntax errors, or attempts to execute invalid code, or throws an exception, this member function throws an Error exception.

Note: This function can only be called from the root thread, since the core JavaScript engine in not reentrant in current versions of PixInsight. Calling this function from a running thread will throw an Error exception.

Warning: You should make sure that your code has been well tested before calling this function. PixInsight pursues efficiency and script execution is no exception. Nothing will protect or watch your code, or help you stop it at any point. If your code enters an infinite loop, it will crash the whole PixInsight platform without remedy. Also bear in mind that scripts are extremely powerful and potentially dangerous if you don't know well what you are doing. What happens during execution of your scripts is your entire responsibility.

◆ GetPhysicalMemoryStatus()

bool pcl::MetaModule::GetPhysicalMemoryStatus	(	size_type &	totalBytes,
		size_type &	availableBytes
	)		const

Acquires current physical memory statistics.

Parameters

[out]	totalBytes	On output, an estimate of the total amount of existing physical memory in bytes.
[out]	availableBytes	On output, an estimate of the amount of memory in bytes that can be allocated by the caller without pushing the system into swap, taking into account memory being used for file caches that can be reclaimed.

The current platform-dependent implementation provides accurate values on supported versions of FreeBSD, Linux, macOS, and Windows.

Returns true if the required system calls and external processes were executed correctly and provided valid values. Returns false in the event of error, in which case the passed variables could be modified, possibly with meaningless values.

See also: AvailablePhysicalMemory(), PhysicalMemoryLoad()

Referenced by AvailablePhysicalMemory(), and PhysicalMemoryLoad().

◆ GetReleaseDate()

virtual void pcl::MetaModule::GetReleaseDate	(	int &	year,
		int &	month,
		int &	day
	)		const

inlinevirtual

Provides release date information for this module.

Parameters

[out]	year	The (full) year this module has been released.
[out]	month	The month this module has been released, 1 <= month <= 12, 1=January.
[out]	day	The day this module has been released, 1 <= day <= 31.

The specified date must be correct; for example, something like 2007/02/30 will not be accepted (the module won't install).

Note: Reimplementing this function is optional. If it is not reimplemented by a derived class to return a valid date, the module will provide no specific release date.

Definition at line 361 of file MetaModule.h.

◆ GetVersion()

void pcl::MetaModule::GetVersion	(	int &	major,
		int &	minor,
		int &	release,
		int &	build,
		IsoString &	language,
		IsoString &	status
	)		const

Provides the version numbers, language code and development status of this module.

Parameters

[out]	major	Main (major) version number.
[out]	minor	Secondary (minor) version number.
[out]	release	Release number.
[out]	build	Build number.
[out]	language	An ISO 639.2 language code (3-letter code) that identifies the primary language of this module.
[out]	status	A string indicating the development status of this module (alpha, beta, release, etc.), or an empty string if no specific status has been specified. For possible values and their meanings, see the documentation for the Version() member function.

This is a utility function, provided for convenience. It parses the version information string returned by the Version() member function, and stores the extracted values in the specified argument variables.

See also: Version()

◆ HasEntitlement()

bool pcl::MetaModule::HasEntitlement ( const IsoString & entitlement )

Returns true iff the module has the specified entitlement.

Entitlements are special permissions granted to installed modules by the PixInsight core application as part of the implemented code security infrastructure.

An entitlement may be necessary to perform certain operations considered potentially dangerous, either for the user or for the PixInsight platform. Entitlements can also be required by running process and format instances to perform some actions considered critical or experimental.

String representations of entitlements normally follow the inverse URL format. Examples:

com.pixinsight.security.pcl.allow-load-resource
com.pixinsight.security.pjsr.allow-write-global-settings
com.pixinsight.developer.experimental-features

◆ IsInstalled()

bool pcl::MetaModule::IsInstalled ( ) const

Returns true iff this module has been successfully installed. Only when the module has been installed, communication with the PixInsight core application is fully operative.

◆ LoadResource()

void pcl::MetaModule::LoadResource	(	const String &	filePath,
		const String &	rootPath = `String()`
	)

Loads a bitmap resource file.

Parameters

filePath	Path to a resource file in Qt's binary resource format (RCC format). This path must point to a location on the local file system (remote resources are not allowed in current PCL versions).
rootPath	Root path for all the loaded bitmap resources. This parameter is an empty string by default.

If the specified resource file does not exist or is invalid, this function will throw an Error exception.

Automatic Resource Location

Resource files can be loaded from arbitrary locations. However, modules typically install their resources on the /rsc/rcc/module directory under the local PixInsight installation. A module can specify the "@module_rcc_dir/" prefix in resource file paths to let the PixInsight core application load the resources from the appropriate standard distribution directory automatically. For example, if a module whose name is "Foo" makes the following call:

LoadResource( "@module_rcc_dir/MyResources.rcc" );

pcl::MetaModule::LoadResource

void LoadResource(const String &filePath, const String &rootPath=String())

the core application will attempt to load the following resource file:

<install-dir>/rsc/rcc/module/Foo/MyResources.rcc

where <install-dir> is the local directory where the running PixInsight core application is installed.

Resource Root Paths

All the resources loaded by a call to this function will be rooted at the specified rootPath under a standard ":/module/<module-name>/" root path prefix set by the PixInsight core application automatically. For example, if the Foo module calls this function as follows:

LoadResource( "@module_rcc_dir/MyResources.rcc" );

and the MyResources.rcc file contains a resource named "foo-icon.png", it will be available at the following resource path:

:/module/Foo/foo-icon.png

This system guarantees that a module will never invalidate or replace existing resources loaded by the core application or other modules. Note that a module still can cause problems by loading resources incorrectly, but these problems cannot propagate outside the failing module.

To ease working with module-defined resources, the standard ":/@module_root/" prefix can be specified in resource file paths:

Bitmap bmp( ":/@module_root/foo-icon.png" );

Continuing with the Foo module example, this call would load the bitmap at ":/module/Foo/foo-icon.png".

References

The Qt Resource System:https://doc.qt.io/qt-6/resources.html

Note: Since PixInsight core version 1.8.9-2, calling this function requires the following security entitlement: 'com.pixinsight.security.pcl.allow-load-resource'.

See also: UnloadResource()

◆ Name()

virtual IsoString pcl::MetaModule::Name ( ) const

pure virtual

Returns an identifier for this module.

The returned string must be a valid C identifier. The identifier must be unique among the identifiers of all installed modules in the calling instance of the PixInsight core application.

This function is not intended to provide a descriptive name, but just a reference identifier for this module. For example, some identifiers of standard PixInsight modules are: Geometry, Image, FITS.

Note: This is a pure virtual function that must be reimplemented by all derived classes.

◆ OnLoad()

virtual void pcl::MetaModule::OnLoad ( )

inlinevirtual

Routine invoked just after this module has been installed.

This function can be reimplemented to perform module-specific initialization procedures.

See also: OnUnload()

Definition at line 481 of file MetaModule.h.

◆ OnUnload()

virtual void pcl::MetaModule::OnUnload ( )

inlinevirtual

Routine invoked just before this module is unloaded in response to an uninstall request, or just before the PixInsight core application is about to terminate execution.

This function can be reimplemented to perform module-specific finalization procedures.

See also: OnLoad()

Definition at line 495 of file MetaModule.h.

◆ operator=()

MetaModule& pcl::MetaModule::operator= ( const MetaModule & )

delete

Copy assignment. This operator is disabled because MetaModule represents unique server-side objects.

◆ OriginalFileName()

virtual String pcl::MetaModule::OriginalFileName ( ) const

inlinevirtual

Returns the original file name of this module.

Note: Reimplementing this function is optional.

Definition at line 338 of file MetaModule.h.

◆ PhysicalMemoryLoad()

float pcl::MetaModule::PhysicalMemoryLoad ( ) const

inline

Returns an estimate of the fraction of physical memory currently in use.

This function acquires estimates of the total amount of existing physical memory and the amount of memory that can be currently allocated by the caller without causing the system to swap. See AvailablePhysicalMemory() for more information.

The returned value is zero in the event of error, or in the range (0,1) if valid, representing the fraction of physical memory that is currently allocated, excluding memory used for reclaimable file caches.

Definition at line 423 of file MetaModule.h.

References GetPhysicalMemoryStatus().

◆ ProcessEvents()

void pcl::MetaModule::ProcessEvents ( bool excludeUserInputEvents = false )

Processes pending user interface and thread events.

Call this function from the root thread (aka GUI thread) to let the PixInsight core application process pending interface events, which may accumulate while your code is running.

Modules typically call this function during real-time preview generation procedures. Calling this function from the root thread ensures that the GUI remains responsive during long, calculation-intensive operations.

If the excludeUserInputEvents parameter is set to true, no user input events will be processed by calling this function. This includes mainly mouse and keyboard events. Unprocessed input events will remain pending and will be processed as appropriate when execution returns to PixInsight's main event handling loop, or when this function is called with excludeUserInputEvents set to false.

When this function is invoked from a running thread, a ProcessAborted exception will be thrown automatically if the Thread::Abort() member function has been previously called for the running thread. This allows stopping running processes in a thread-safe and controlled way. For more information, read the documentation for the Thread class.

Note: Do not call this function too frequently from the root thread, as doing so may degrade the performance of the whole PixInsight graphical interface. For example, calling this function at 250 ms intervals is reasonable and more than sufficient in most cases. Normally, you should only need to call this function during real-time image and graphics generation procedures, or from time-consuming processes, especially from multithreaded code.

See also: Thread, Thread::Abort()

◆ ReadableVersion()

IsoString pcl::MetaModule::ReadableVersion ( ) const

Returns a readable version string for this module of the form:

<module-name> version M.m.r.b

where <module-name> is the string returned by the (reimplemented) Name() virtual member function, and M.m.r.b are the major, minor, release and build numbers, as provided by GetVersion().

The string returned by this member function is suitable to be used for module identification purposes, including metadata such as FITS keywords.

◆ TradeMarks()

virtual String pcl::MetaModule::TradeMarks ( ) const

inlinevirtual

Returns a string with a trade mark or a list of trade marks.

To specify multiple trade marks, separate them with commas.

Note: Reimplementing this function is optional.

Definition at line 328 of file MetaModule.h.

◆ UniqueId()

virtual const char* pcl::MetaModule::UniqueId ( ) const

virtual

Deprecated:: This member function has been deprecated. It is maintained for compatibility with existing code - do not use it in newly produced code.

◆ UnloadResource()

void pcl::MetaModule::UnloadResource	(	const String &	filePath,
		const String &	rootPath = `String()`
	)

Unloads a bitmap resource file.

After calling this function, all the resources available from the specified resource file will be unavailable. The filePath and rootPath arguments must be identical to the ones used when the resource was loaded by a call to LoadResource().

If the specified resource has not been loaded, or if there are active references to the resource (for example, because one or more existing Bitmap objects depend on data stored in the resource), this function will throw an Error exception.

Note: Since PixInsight core version 1.8.9-2, calling this function requires the following security entitlement: 'com.pixinsight.security.pcl.allow-unload-resource'.

See also: LoadResource()

◆ Version()

virtual const char* pcl::MetaModule::Version ( ) const

pure virtual

Returns a version information string for this PixInsight module.

This member function must be reimplemented to return the starting address of an invariant sequence of 8-bit characters. The returned character string shall have the following format:

PIXINSIGHT_MODULE_VERSION_<version-string><nul>

where:

PIXINSIGHT_MODULE_VERSION_ is a mandatory prefix. It must be included literally at the beginning of the returned string.
<version-string> is a mandatory version string composed by at least 17 characters. It must have the following format:

MM.mm.rr.bbbb.LLL[.<status>]

where MM is the major version number, mm is the minor version number, rr is the release version number, and bbbb is a build number. The three version numbers must be in the range from zero to 99. The build number must be in the range from 1 to

The four numbers must be left padded with zeros in the returned string, if necessary, and their values are supposed to increase with each successive version of the module.

LLL is a three-letter ISO 639.2 language code, which must correspond to the primary language of the module (generally, the language used to write visible messages and information of the user interface).

<status> is an optional version status word. If included, it can be one of the following:

alpha Indicates an alpha version of the module (a version at the early development stages, where the final features and functionality of the module still have not been defined).

beta Indicates a beta version of the module (a development version that still is not suitable for production release).

rc<n> A release candidate version (an almost finished version, still under development but very close to a final release). <n> is an arbitrary release candidate number.

release Indicates a release (final, production) version.

exp An experimental version (a special development version, not intended for public release; usually a confidential version distributed among the members of a development team)

If no status is specified in the version information string, a release version will be assumed.

Note: This is a pure virtual function that must be reimplemented by all derived classes.

See also: GetVersion()

The documentation for this class was generated from the following file:

MetaModule.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MetaModule() [1/2]

◆ ~MetaModule()

◆ MetaModule() [2/2]

Member Function Documentation

◆ Allocate()

◆ Author()

◆ AvailablePhysicalMemory()

◆ Company()

◆ Copyright()

◆ Deallocate()

◆ Description()

◆ EvaluateScript()

◆ GetPhysicalMemoryStatus()

◆ GetReleaseDate()

◆ GetVersion()

◆ HasEntitlement()

◆ IsInstalled()

◆ LoadResource()

◆ Name()

◆ OnLoad()

◆ OnUnload()

◆ operator=()

◆ OriginalFileName()

◆ PhysicalMemoryLoad()

◆ ProcessEvents()

◆ ReadableVersion()

◆ TradeMarks()

◆ UniqueId()

◆ UnloadResource()

◆ Version()