Attention

Fluxion/flux-sched (both refer to the same project) is under development and its interfaces are not yet stable. APIs are not exported or exposed to external consumers. This documentation is meant for developers of Fluxion.

Resource

Resource graph and matching infrastructure.

Evaluators

namespace Flux

namespace resource_model

class expr_eval_api_t

#include <expr_eval_api.hpp>

Expression evaluation API class. Parse and validate or evaluate an expression using the state of each individual predicates provided the target state of expr_eval_target_t. Currently supported expression: An expression is one or more predicates combined with logical conjunction ("and"), disjunction ("or"), or parentheses ("()"). The evaluation order is consistent with these operators used in predicate calculus.

Public Functions

int validate(const std::string &expr, const expr_eval_target_base_t &target)

Validate if an expression is valid w/ respect to the target state.

Parameters:

expr -- expression string
target -- expression evaluation target of expr_eval_target_base_t type

Returns:

0 on success; -1 on error

int evaluate(const std::string &expr, const expr_eval_target_base_t &target, bool &result)

Evaluate if an expression is valid w/ respect to the target state.

Parameters:

expr -- expression string
target -- expression evaluation target of expr_eval_target_base_t type

Returns:

0 on success; -1 on error

int extract(const std::string &expr, const expr_eval_target_base_t &target, std::vector<std::pair<std::string, std::string>> &predicates)

Extract jobid and agfilter bool if provided.

Parameters:

expr -- expression string
target -- expression evaluation target
jobid -- jobid optionally specified in expression
agfilter -- bool optionally specified in expression of expr_eval_target_base_t type

Returns:

0 on success; -1 on error

Private Types

enum class pred_op_t : int

Values:

enumerator AND = 0

enumerator OR = 1

enumerator UNKNOWN = 2

Private Functions

bool is_paren(const std::string &expr, std::size_t at) const

size_t find_closing_paren(const std::string &expr, size_t at) const

int parse_expr_leaf(const std::string &expr, size_t at, size_t &tok, size_t &len) const

int parse_expr_paren(const std::string &expr, size_t at, size_t &tok, size_t &len) const

pred_op_t parse_pred_op(const std::string &e, size_t at, size_t &next) const

int validate_leaf(const std::string &expr, const expr_eval_target_base_t &target)

int validate_paren(const std::string &expr, const expr_eval_target_base_t &target, size_t at, size_t &nx)

int validate_pred(pred_op_t op) const

int evaluate_leaf(const std::string &expr, const expr_eval_target_base_t &target, bool &result)

int evaluate_paren(const std::string &expr, const expr_eval_target_base_t &target, size_t at, size_t &next, bool &result)

int evaluate_pred(pred_op_t op, bool result2, bool &result1) const

int extract_leaf(const std::string &expr, const expr_eval_target_base_t &target, std::vector<std::pair<std::string, std::string>> &predicates)

int extract_paren(const std::string &expr, const expr_eval_target_base_t &target, size_t at, size_t &next, std::vector<std::pair<std::string, std::string>> &predicates)

Traversers

Graph traversal implementations for resource matching.

namespace Flux

namespace resource_model

class dfu_traverser_t

#include <dfu.hpp>

Depth-First-and-Up traverser. Perform depth-first visit on the dominant subsystem and upwalk on each and all of the auxiliary subsystems selected by the matcher callback object (dfu_match_cb_t). Corresponding match callback methods are invoked at various well-defined graph visit events.

Public Functions

dfu_traverser_t(const std::string policy = "simple")

dfu_traverser_t(std::shared_ptr<resource_graph_db_t> db, std::shared_ptr<dfu_match_cb_t> m, const std::string policy = "simple")

dfu_traverser_t(const dfu_traverser_t &o)

dfu_traverser_t(dfu_traverser_t &&o) = default

dfu_traverser_t &operator=(const dfu_traverser_t &o)

dfu_traverser_t &operator=(dfu_traverser_t &&o) = default

~dfu_traverser_t()

const resource_graph_t *get_graph() const

const std::shared_ptr<const resource_graph_db_t> get_graph_db() const

const std::shared_ptr<const dfu_match_cb_t> get_match_cb() const

const std::string &err_message() const

const unsigned int get_total_preorder_count() const

const unsigned int get_total_postorder_count() const

void set_graph_db(std::shared_ptr<resource_graph_db_t> db)

void set_match_cb(std::shared_ptr<dfu_match_cb_t> m)

void clear_err_message()

bool is_initialized() const

int initialize()

Prime the resource graph with subtree plans. Assume that resource graph, roots and match callback have already been registered. The subtree plans are instantiated on certain resource vertices and updated with the information on their subtree resources. For example, the subtree plan of a compute node resource vertex can be configured to track the number of available compute cores in aggregate at its subtree. dfu_match_cb_t provides an interface to tell this initializer what subtree resources to track at higher-level resource vertices.

Returns:: 0 on success; -1 on error. EINVAL: graph, roots or match callback not set. ENOTSUP: roots does not contain a subsystem the match callback object need to use.

int initialize(std::shared_ptr<resource_graph_db_t> db, std::shared_ptr<dfu_match_cb_t> m)

Prime the resource graph with subtree plans. Assume that resource graph, roots and match callback have already been registered. The subtree plans are instantiated on certain resource vertices and updated with the information on their subtree resources. For example, the subtree plan of a compute node resource vertex can be configured to track the number of available compute cores in aggregate at its subtree. dfu_match_cb_t provides an interface to tell this initializer what subtree resources to track at higher-level resource vertices.

Parameters:

g -- resource graph of resource_graph_t type.
roots -- map of root vertices, each is a root of a subsystem.
m -- match callback object of dfu_match_cb_t type.

Returns:

0 on success; -1 on error. EINVAL: graph, roots or match callback not set. ENOTSUP: roots does not contain a subsystem the match callback uses.

int run(Jobspec::Jobspec &jobspec, std::shared_ptr<match_writers_t> &writers, match_op_t op, int64_t id, int64_t *at)

Begin a graph traversal for the jobspec and allocate, reserve or check its satisfiability on the resources in the resource graph. Best-matching resources are selected in accordance with the scoring done by the match callback methods. Initialization must have successfully finished before this method is called.

Parameters:

jobspec -- Jobspec object.
writers -- vertex/edge writers to emit the matched labels
op -- schedule operation: allocate, allocate_with_satisfiability, allocate_orelse_reserve or satisfiability.
id -- job ID to use for the schedule operation.
at[out] -- when the job is scheduled if reserved.

Returns:

0 on success; -1 on error. EINVAL: graph, roots or match callback not set. ENOTSUP: roots does not contain a subsystem the match callback uses. EBUSY: cannot match because resources/devices are currently in use. ENODEV: unsatisfiable jobspec because no resources/devices can satisfy the request.

int run(const std::string &str, std::shared_ptr<match_writers_t> &writers, std::shared_ptr<resource_reader_base_t> &reader, int64_t id, int64_t at, uint64_t duration)

Read str which is a serialized allocation data (e.g., written in JGF) with rd, and traverse the resource graph to update it with this data.

Parameters:

str -- allocation string such as written in JGF.
writers -- vertex/edge writers to emit the matched labels
reader -- reader object that deserialize str to update the graph
id -- job ID to use for the schedule operation.
at -- the starting time of this job.
duration -- the duration of this job

Returns:

0 on success; -1 on error. TODO: Fill in errnos

int find(std::shared_ptr<match_writers_t> &writers, const std::string &criteria)

Traverse the resource graph and emit those resources whose status is matched with the matching criteria.

Parameters:

writers -- vertex/edge writers to emit the matched labels
criteria --
matching criteria expression string. Each individual criterion is expressed as a key-value pair, representing a predicate p(x) where key is is p and value is x. Currently supported expressions are "status={up|down}", "sched-now={allocated|free}", "sched-future={reserved|free}, or any combination

of them separated with "and", "or", or a whitespace

which is also interpreted as "and" logical operator of two expressions. Parentheses are supported to group expressions with a higher operator precedence. For example, in "status=up and

(sched-now=allocated or sched-future=reserved)" The parenthesized expression is evaluated before taking the "and" operator with the the result of the first predicate. Other extra whitespaces around predicates are ignored.

Returns:

0 on success; -1 on error.

int remove(int64_t jobid)

Remove the allocation/reservation referred to by jobid and update the resource state.

Parameters:: jobid -- job id.
Returns:: 0 on success; -1 on error. EINVAL: graph, roots or match callback not set.

int remove(const std::string &to_cancel, std::shared_ptr<resource_reader_base_t> &reader, int64_t jobid, bool &full_cancel)

Remove the allocation/reservation referred to by jobid and update the resource state.

Parameters:

R_to_cancel -- deallocation string such as written in JGF.
reader -- reader object that deserialize str to update the graph
jobid -- job id.
full_cancel -- bool indicating if the partial cancel cancelled all job resources

Returns:

0 on success; -1 on error. EINVAL: graph, roots or match callback not set.

int remove(const std::set<int64_t> &ranks)

Remove the allocation/reservation referred to by a set of ranks and update the resource state.

Parameters:: ranks -- set of ranks to deallocate.
Returns:: 0 on success; -1 on error. EINVAL: graph, roots or match callback not set.

int remove_subgraph(const std::string &target)

Remove a subgraph rooted at the target path.

Parameters:: target -- string path to the root of the subgraph to remove
Returns:: 0 on success; -1 on error. EINVAL: graph, roots or match callback not set.

int remove_subgraph(const std::set<int64_t> &ranks)

Remove a subgraph corresponding to given ranks.

Parameters:: ranks -- Set of ranks to remove from the resource graph.
Returns:: 0 on success; -1 on error. EINVAL: graph, roots or match callback not set.

int mark(const std::string &root_path, resource_pool_t::status_t status)

Mark the resource status up|down|etc starting at subtree_root.

Parameters:

root_path -- path to the root of the subtree to update.
status -- new status value

Returns:

0 on success; -1 on error. EINVAL: roots or by_path not found.

int mark(std::set<int64_t> &ranks, resource_pool_t::status_t status)

Mark the resource status up|down|etc for subgraph represented by ranks.

Parameters:

ranks -- set of ranks representing the subgraph to update.
status -- new status value

Returns:

0 on success; -1 on error. EINVAL: roots or by_path not found.

Private Functions

int is_satisfiable(Jobspec::Jobspec &jobspec, detail::jobmeta_t &meta, bool x, vtx_t root, std::unordered_map<resource_type_t, int64_t> &dfv)

int request_feasible(detail::jobmeta_t const &meta, match_op_t op, vtx_t root, std::unordered_map<resource_type_t, int64_t> &dfv)

int schedule(Jobspec::Jobspec &jobspec, detail::jobmeta_t &meta, bool x, match_op_t op, vtx_t root, std::unordered_map<resource_type_t, int64_t> &dfv)

Private Members

bool m_initialized = false

unsigned int m_total_preorder = 0

unsigned int m_total_postorder = 0

std::shared_ptr<detail::dfu_impl_t> traverser

Policies

Resource selection policies for graph traversal and matching.

namespace Flux

namespace resource_model

class dfu_match_cb_t : public Flux::resource_model::matcher_data_t, public Flux::resource_model::matcher_util_api_t

#include <dfu_match_cb.hpp>

Base DFU matcher class. Define the set of visitor methods that are called back by a DFU resource-graph traverser.

Subclassed by Flux::resource_model::greater_interval_first_t, Flux::resource_model::multilevel_id_t< FOLD >, Flux::resource_model::var_aware_t

Public Functions

dfu_match_cb_t()

dfu_match_cb_t(const std::string &name)

dfu_match_cb_t(const dfu_match_cb_t &o)

dfu_match_cb_t &operator=(const dfu_match_cb_t &o)

virtual ~dfu_match_cb_t()

virtual int dom_finish_graph(subsystem_t subsystem, const std::vector<Flux::Jobspec::Resource> &resources, const resource_graph_t &g, scoring_api_t &dfu)

Called back when all of the graph vertices and edges have been visited. Must be overridden by a derived class if this visit event should be programed.

Parameters:

subsystem -- subsystem_t object of the dominant subsystem.
resources -- vector of resources to be matched.
g -- filtered resource graph.
dfu -- score interface object - See utilities/README.md

Returns:

return 0 on success; otherwise -1.

virtual int dom_finish_slot(subsystem_t subsystem, scoring_api_t &dfu): Called back on each postorder visit of a group of slot resources (resources that can be contained within one or more slots) of the dominant subsystem.

virtual int dom_discover_vtx(vtx_t u, subsystem_t subsystem, const std::vector<Flux::Jobspec::Resource> &resources, const resource_graph_t &g)

Called back on each preorder visit of the dominant subsystem. Must be overridden by a derived class if this visit event should be programed.

Parameters:

u -- descriptor of the visiting vertex.
subsystem -- subsystem_t object of the dominant subsystem.
resources -- vector of resources to be matched (resource section of a jobspec).
g -- filtered resource graph.

Returns:

return 0 on success; otherwise -1.

virtual int dom_finish_vtx(vtx_t u, subsystem_t subsystem, const std::vector<Flux::Jobspec::Resource> &resources, const resource_graph_t &g, scoring_api_t &dfu)

Called back on each postorder visit of the dominant subsystem. Must be overridden by a derived class if this visit event should be programed. Should return a score calculated based on the subtree and up walks using the score API object (dfu). Any score above MATCH_MET is qualified to be a match.

Parameters:

u -- descriptor of the visiting vertex
subsystem -- subsystem_t object of the dominant subsystem
resources -- vector of resources to be matched
g -- filtered resource graph
dfu -- score interface object — See utilities/README.md

Returns:

return 0 on success; otherwise -1

virtual int aux_discover_vtx(vtx_t u, subsystem_t subsystem, const std::vector<Flux::Jobspec::Resource> &resources, const resource_graph_t &g)

Called back on each pre-up visit of an auxiliary subsystem. Must be overridden by a derived class if this visit event should be programed.

Parameters:

u -- descriptor of the visiting vertex
subsystem -- subsystem_t of the auxiliary subsystem being walked
resources -- vector of resources to be matched
g -- filtered resource graph

Returns:

return 0 on success; otherwise -1

virtual int aux_finish_vtx(vtx_t u, subsystem_t subsystem, const std::vector<Flux::Jobspec::Resource> &resources, const resource_graph_t &g, scoring_api_t &dfu)

virtual int set_stop_on_k_matches(unsigned int k)

virtual int get_stop_on_k_matches() const

void incr()

void decr()

std::string level()

Private Members

int m_trav_level