Module development

find_package(adaptyst REQUIRED)
target_link_libraries(example PUBLIC adaptyst::adaptyst)

find_package(adaptyst REQUIRED)
set(INSTALL_DIR "${ADAPTYST_MODULE_PATH}/my_module")

// These two lines are REQUIRED.
#define ADAPTYST_MODULE_ENTRYPOINT
#include <adaptyst/hw.h>

// Called once when a module instance is initialised by
// Adaptyst (there may be several module instances within
// an entity up to the limit defined in max_count_per_entity).
//
// Use the value of the "module_id" parameter in all Adaptyst
// API calls requiring an ID of type amod_t.
//
// The return value indicates whether the initialisation
// has succeeded.
bool adaptyst_module_init(amod_t module_id) {
    return true;
}

// Called when a module instance is expected to process
// a workflow IR stored in the "ir" parameter.
// It is up to the module to decide what parts of the IR to
// process. Adaptyst module API methods should be used for
// saving module outputs.
//
// The type of the "ir" parameter is a C struct compatible
// with many different IR types: see the
// Doxygen documentation of adaptyst/hw.h to see how it
// is structured.
//
// Use the value of the "module_id" parameter in all Adaptyst
// API calls requiring an ID of type amod_t.
//
// This function is guaranteed to be called after
// adaptyst_module_init().
//
// The return value indicates whether the module
// has successfully processed the IR.
bool adaptyst_module_process(amod_t module_id, ir workflow) {
    return true;
}

// Called once when a module instance is finalised/closed
// by Adaptyst.
//
// Use the value of the "module_id" parameter in all Adaptyst
// API calls requiring an ID of type amod_t.
//
// This function is guaranteed to be called last.
void adaptyst_module_close(amod_t module_id) {

}

// Called when a workflow calls adaptyst_region_start()
// (see "Running Adaptyst" -> "Code regionisation"),
// with the following arguments:
// * module_id: use its value in all Adaptyst API calls requiring
//   an ID of type amod_t.
// * name: the name of the region as passed to adaptyst_region_start().
// * part_id: a string indicating what part of the workflow
//   adaptyst_region_start() has been called in. At the moment,
//   it is always in form of "<PID>_<TID>" where <PID> and <TID>
//   are the process and thread ID respectively.
// * timestamp_str: a string representing the timestamp of the
//   adaptyst_region_start() call in nanoseconds, it's "-1" if
//   undefined/unknown.
//
// The return value indicates whether the module has processed
// the region start successfully.
bool adaptyst_region_start(amod_t module_id, const char *name,
                           const char *part_id, const char *timestamp_str) {

}

// Called when a workflow calls adaptyst_region_end()
// (see "Running Adaptyst" -> "Code regionisation"),
// with the following arguments:
// * module_id: use its value in all Adaptyst API calls requiring
//   an ID of type amod_t.
// * name: the name of the region as passed to adaptyst_region_end().
// * part_id: a string indicating what part of the workflow
//   adaptyst_region_end() has been called in. At the moment,
//   it is always in form of "<PID>_<TID>" where <PID> and <TID>
//   are the process and thread ID respectively.
// * timestamp_str: a string representing the timestamp of the
//   adaptyst_region_end() call in nanoseconds, it's "-1" if
//   undefined/unknown.
//
// The return value indicates whether the module has processed
// the region end successfully.
bool adaptyst_region_end(amod_t module_id, const char *name,
                         const char *part_id, const char *timestamp_str) {

}

// The human-friendly name of a module.
volatile const char *name = "MyModule";

// The human-friendly version of a module.
volatile const char *version = "1.0.0";

// The non-negative version numbers of a module, with
// the last element being negative (-1 is standard here).
//
// Note that the last element is always ignored, it is used only
// for indicating the end of the array.
//
// At least one non-negative number must be defined.
//
// Version comparisons are done lexicographically,
// e.g. { 3, <anything> } > { 2, <anything> },
// { 3, 2, <anything> } > { 3, 1, <anything> },
// { 11, 2, -1 } > { 11, -1 },
// { 12, 5, 3, -1 } > { 12, 4, 88, -1 } etc.
//
// Please bear in mind that {<xyz>, 0, ..., 0, -1} > {<xyz>, -1},
// where <xyz> is any combination of non-negative numbers and
// the number of zeroes on the left-hand side is anything greater
// than or equal to 1.
volatile const int version_nums[] = { 1, 0, 0, -1 };

// The maximum number of instances of a module that can be
// spawned in an entity. 0 means unlimited.
//
// This constant is optional, the default value is 0.
volatile const unsigned int max_count_per_entity = 0;

volatile const char *options[] = {
    // The names of all user-settable options provided by
    // a module, with the last element being NULL.
    NULL
};

volatile const char *tags[] = {
    // The module tags that will be attached
    // automatically to a node, with the last element
    // being NULL.
    //
    // Tags can be used for a variety of reasons,
    // e.g. to verify whether a GPU module is attached
    // to a node that is connected with a CPU node.
    //
    // All tags used by a module are public-facing
    // and thus must be visibly documented to the outside
    // world, especially if a module is closed-source.
    NULL
};

volatile const char *log_types[] = {
    // The names of all types of logs that a module
    // can produce, with the last element being NULL.
    NULL
};

// Each option XYZ can accept either a single or an array value, NOT both.

// *** For each option XYZ in the "options" array with a single value: ***

// Help message, required.
volatile const char *XYZ_help = "XYZ help message";

// Option value type, required.
volatile const option_type XYZ_type = UNSIGNED_INT;

// Default option value, optional (the option becomes
// required to be set by a user if this is not provided).
//
// The type of this constant is determined by the value
// of XYZ_type. See the Doxygen documentation of
// option_type for matchings between option_type values
// and C types.
volatile const unsigned int XYZ_default = 1;

// *** For each option XYZ in the "options" array with an array value: ***

// Help message, required.
volatile const char *XYZ_help = "XYZ help message";

// Value type of every option array element, required.
volatile const option_type XYZ_array_type = UNSIGNED_INT;

// Default option value, optional (the option becomes
// required to be set by a user if this is not provided).
//
// The type of this array constant is determined by the value
// of XYZ_array_type. See the Doxygen documentation of
// option_type for matchings between option_type values
// and C types.
volatile const unsigned int XYZ_array_default[] = {};

// Number of elements in the default option value, required
// if XYZ_array_default is set.
volatile const unsigned int XYZ_array_default_size = 0;

// Called when a user double-clicks an analysable in a system graph
// (e.g. a node) and asks to open a specific module. This function should
// create a new window representing the starting point
// for exploring outputs produced by the module.
//
// Parameters:
// * entity_id (String): the ID of an entity of an analysable
//   double-clicked by a user.
// * analysable_id (String): the ID of an analysable double-clicked
//   by a user.
// * session (Object): a Session object corresponding to the
//   currently-selected performance analysis session.
function createRootWindow(entity_id, analysable_id, session) {

}

// Called when an arrangement is loaded. This function should
// return a class whose getType() returns the same string as the
// one provided in the "type" parameter here. If the class
// can't be found, undefined should be returned.
//
// Parameters:
// * type (String): the type of a requested window class.
function getWindowClass(type) {

}

export { createRootWindow, getWindowClass };

<svg xmlns="http://www.w3.org/2000/svg" data-icon="<icon type>"
 other-attributes>
  Your extra SVG tags, e.g. <title>
</svg>

def get_mod_obj(session_id, entity, analysable, options):
    """
    Get an object of a main module class which must inherit from
    Module.

    :param Identifier session_id: The identifier of a performance
                                  analysis session.
    :param str entity: The name of an entity where the module is
                       located.
    :param str analysable: The name of an analysable where the module
                           is located.
    :param dict options: The dictionary of module options provided
                         by the user in the system graph YAML file
                         if any. It can be None.
    """
    pass

from adaptystanalyser import Identifier, Module


class MyModule(Module):
    def __init__(self, session_id: Identifier, entity: str,
                 analysable: str, options):
        # Avoid any expensive calls here, these should be put
        # in _load() instead.
        self._path = session_id.get_detailed_path(
            entity, analysable, self.get_name()
        )
        self._options = options
        self._summary = None

    def get_name(self):
        # This must match the module name specified in the metadata.
        return "my_module"

    def _load(self):
        # All expensive processing should be implemented here.
        with (self._path / "summary.json").open() as file:
            self._summary = json.load(file)

    @Module.needs_loading
    def get_summary(self):
        # Public module-specific method for API users.
        # Note the @Module.needs_loading decorator here:
        # self._summary must be set by _load() first.
        return self._summary

    def get_summary_window(self):
        # See the "Exportable windows" subsection for
        # the SummaryWindow code.
        return SummaryWindow(self)

    def process_post_request(self, data):
        # This method is called when handling POST requests.
        if "summary" in data:
            return self.get_summary()

        return "", 401


def get_mod_obj(session_id, entity, analysable, options):
    return MyModule(session_id, entity, analysable, options)

from adaptystanalyser import Analysable, Module, Session, Window


class SummaryWindow(Window):
    def __init__(self, module: Module):
        self._module = module

    def get_module(self) -> Module:
        """
        Return the Module object associated with the window.
        """
        return self._module

    def get_type(self) -> str:
        """
        Return the type identifier of the window. On the client
        side in JavaScript, this must match the return value of
        getType() in the corresponding module class and be recognised by
        getWindowClass().
        """
        return "my_module_summary"

    def get_constr_args(self) -> list:
        """
        Return the arguments required to construct the window.
        """
        return []

    def get_dependencies(self) -> list:
        """
        Return the Window objects on which this window depends.
        """
        return []

    def get_init_data(self):
        """
        Return the initialisation data required by the window.
        """
        return None

    def get_data(self):
        """
        Return the data stored by the window.
        """
        return None

    def get_session(self) -> Session:
        """
        Return the performance analysis session associated with the window.
        """
        return self._module.get_session()

    def get_analysable(self) -> Analysable:
        """
        Return the Analysable object associated with the window.
        """
        return self._module.get_analysable()

window = module.get_summary_window()
window.set_custom_title("Analysis summary")

arrangement_id, update_token = Window.save_arrgmt(
    window,
    name="analysis-summary"
)
url_suffix = Window.get_arrgmt_url(arrangement_id)

name: ModuleName
version: 1.0.0
short_desc: Short module description.

# The minimum supported version of the corresponding
# Adaptyst module. If a user tries to inspect data produced
# by an older version of the module, they will get an error.
#
# Use the same versioning scheme as in version_nums in an
# Adaptyst module shared library (negative numbers shouldn't be
# included).
min_module_version: [1, 0, 0]

# Python dependencies. Use the pip requirements.txt format.
# If your module has no Python dependencies, omit this section.
python_dependencies:
  - package1
  - package2
  - package3

# JavaScript dependencies expected to be found in "deps" folder
# along with CSS stylesheets if any, in form of full filenames including
# extensions. Only .js, .cjs, and .css files are accepted.
#
# If your module has no JavaScript/CSS dependencies as files, omit
# this section.
js_dependencies:
  - script1.js
  - script2.js
  - script2.css

# JavaScript dependencies to be downloaded along with CSS
# stylesheets if any, in form of HTTP(S) URLs (e.g. pointing to CDNs).
# Only .js, .cjs, and .css files are accepted.
#
# If your module has no JavaScript/CSS dependencies as URLs, omit
# this section.
js_url_dependencies:
  - https://example.com/example.js
  - https://example.com/example.css