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.
REAPI
C Interface
Typedefs
-
typedef struct reapi_cli_ctx reapi_cli_ctx_t
Functions
-
reapi_cli_ctx_t *reapi_cli_new()
Create and initialize reapi_cli context
-
reapi_cli_ctx_t *reapi_cli_clone(reapi_cli_ctx_t *ctx)
Deep-copy a reapi_cli context, including the full resource graph state, all allocations and reservations, and up/down status. The returned context is completely independent of the original: operations on the clone do not affect the original, making it suitable for forward simulation.
- Parameters:
ctx -- source reapi_cli_ctx_t context object
- Returns:
new independent context on success; NULL on error
-
void reapi_cli_destroy(reapi_cli_ctx_t *ctx)
Destroy reapi cli context
- Parameters:
ctx -- reapi_cli_ctx_t context object
-
int reapi_cli_initialize(reapi_cli_ctx_t *ctx, const char *rgraph, const char *options)
Initialize Fluxion with resource graph
- Parameters:
ctx -- reapi_cli_ctx_t context object
rgraph -- string encoding the resource graph
options -- json string initialization options
-
int reapi_cli_match(reapi_cli_ctx_t *ctx, match_op_t match_op, const char *jobspec, uint64_t *jobid, bool *reserved, char **R, int64_t *at, double *ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
ctx -- reapi_cli_ctx_t context object
match_op -- match_op_t: set to specify the specific match option from 1 of 4 choices: MATCH_ALLOCATE: try to allocate now and fail if resources aren't available. MATCH_ALLOCATE_ORELSE_RESERVE : Try to allocate and reserve if resources aren't available now. MATCH_SATISFIABILITY: Do a satisfiablity check and do not allocate. MATCH_ALLOCATE_W_SATISFIABILITY: try to allocate and run satisfiability check if resources are not available.
jobspec -- jobspec string.
jobid -- jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_match_with_jobid(reapi_cli_ctx_t *ctx, match_op_t match_op, const char *jobspec, uint64_t jobid, bool *reserved, char **R, int64_t *at, double *ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy. This function is identical to reapi_cli_match() in all respects except the jobid is provided by the caller, who is responsible for ensuring uniqueness. N.B. To avoid jobid collisions, this call should not be mixed with the other match calls that allocate them internally.
- Parameters:
ctx -- reapi_cli_ctx_t context object
match_op -- match_op_t: set to specify the specific match option from 1 of 4 choices: MATCH_ALLOCATE: try to allocate now and fail if resources aren't available. MATCH_ALLOCATE_ORELSE_RESERVE : Try to allocate and reserve if resources aren't available now. MATCH_SATISFIABILITY: Do a satisfiablity check and do not allocate. MATCH_ALLOCATE_W_SATISFIABILITY: try to allocate and run satisfiability check if resources are not available.
jobspec -- jobspec string.
jobid -- jobid provided by caller
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_match_allocate(reapi_cli_ctx_t *ctx, bool orelse_reserve, const char *jobspec, uint64_t *jobid, bool *reserved, char **R, int64_t *at, double *ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
ctx -- reapi_cli_ctx_t context object
orelse_reserve -- Boolean: if false, only allocate; otherwise, first try to allocate and if that fails, reserve.
jobspec -- jobspec string.
jobid -- jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_match_satisfy(reapi_cli_ctx_t *ctx, const char *jobspec, bool *sat, double *ov)
Run Satisfiability check for jobspec. When sat is true, there is no error and the job is satisfiable. When sat is false and there is no error, the job is not satisfiable. When sat is false and there is an error, satisfiability is unknown.
- Parameters:
ctx -- reapi_cli_ctx_t context object
jobspec -- jobspec string.
sat -- bool sat into which to return if jobspec is satisfiable.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_update_allocate(reapi_cli_ctx_t *ctx, const uint64_t jobid, const char *R, int64_t *at, double *ov, const char **R_out)
Update the resource state with R.
- Parameters:
ctx -- reapi_cli_ctx_t context object
jobid -- jobid of the uint64_t type.
R -- R string
at -- return the scheduled time
ov -- return the performance overhead in terms of elapse time needed to complete the match operation.
R_out -- return the updated R string.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_add_subgraph(reapi_cli_ctx_t *ctx, const char *R_subgraph)
Add a subgraph to the resource graph with R_subgraph.
- Parameters:
ctx -- reapi_cli_ctx_t context object
R_subgraph -- JGF string of subgraph to attach to existing resources. Supports adding a JGF subgraph including the path from the cluster root to the subgraph root.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_remove_subgraph(reapi_cli_ctx_t *ctx, const char *subgraph_path)
Remove a subgraph from the resource graph with subgraph_path.
- Parameters:
ctx -- reapi_cli_ctx_t context object
subgraph_path -- String representing the path from the cluster root to the root of the subgraph to be removed from the resource graph
- Returns:
0 on success; -1 on error.
-
int reapi_cli_cancel(reapi_cli_ctx_t *ctx, const uint64_t jobid, bool noent_ok)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_cli_ctx_t context object
jobid -- jobid of the uint64_t type.
noent_ok -- don't return an error on nonexistent jobid
- Returns:
0 on success; -1 on error.
-
int reapi_cli_partial_cancel(reapi_cli_ctx_t *ctx, const uint64_t jobid, const char *R, bool noent_ok, bool *full_removal)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- jobid of the uint64_t type.
R -- R string to remove
noent_ok -- don't return an error on nonexistent jobid
full_removal -- don't return an error on nonexistent jobid
- Returns:
0 on success; -1 on error.
-
int reapi_cli_info(reapi_cli_ctx_t *ctx, const uint64_t jobid, char **mode, bool *reserved, int64_t *at, double *ov)
Get the information on the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_cli_ctx_t context object
jobid -- const jobid of the uint64_t type.
mode -- return string containing the job state.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_cli_find(reapi_cli_ctx_t *ctx, const char *criteria, const char *format, char **R)
Find resources matching the criteria and return them in R format.
- Parameters:
ctx -- reapi_cli_ctx_t context object
criteria -- Search criteria string (e.g., "sched-now=allocated", "status=down", etc.)
format -- Optional output format string (e.g., "rv1_nosched", "jgf"). If NULL, uses the context's configured match_format.
R -- JSON string containing matching resources in R format, or NULL if nothing matched. Caller must free with free().
- Returns:
0 on success; -1 on error.
-
int reapi_cli_stat(reapi_cli_ctx_t *ctx, int64_t *V, int64_t *E, int64_t *J, double *load, double *min, double *max, double *avg)
Get the performance information about the resource infrastructure.
- Parameters:
ctx -- reapi_cli_ctx_t context object
V -- Number of resource vertices
E -- Number of edges
J -- Number of jobs
load -- Graph load time
min -- Min match time
max -- Max match time
avg -- Avg match time
- Returns:
0 on success; -1 on error.
-
const char *reapi_cli_get_err_msg(reapi_cli_ctx_t *ctx)
Get the reapi cli error message.
- Parameters:
ctx -- reapi_cli_ctx_t context object
- Returns:
heap-allocated string containing the error message; the caller owns it and must free() it.
-
void reapi_cli_clear_err_msg(reapi_cli_ctx_t *ctx)
Clear the reapi cli error message.
- Parameters:
ctx -- reapi_cli_ctx_t context object
-
int reapi_cli_set_status(reapi_cli_ctx_t *ctx, const char *resource_path, resource_status_t status)
Set resource status (up or down) for a resource at the specified path.
- Parameters:
ctx -- reapi_cli_ctx_t context object
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- RESOURCE_UP or RESOURCE_DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
int reapi_cli_get_status(reapi_cli_ctx_t *ctx, const char *resource_path, resource_status_t *status)
Get resource status for a resource at the specified path.
- Parameters:
ctx -- reapi_cli_ctx_t context object
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- Pointer to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
int reapi_cli_set_rank_status(reapi_cli_ctx_t *ctx, const char *ranks, resource_status_t status)
Set resource status (up or down) for the subtree root (typically node) of each rank in a set. Unknown ranks are silently ignored.
- Parameters:
ctx -- reapi_cli_ctx_t context object
ranks -- RFC 22 idset string representing rank set, or "all"
status -- RESOURCE_UP or RESOURCE_DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters or unexpected internal error
-
int reapi_cli_get_rank_status(reapi_cli_ctx_t *ctx, const char *rank, resource_status_t *status)
Get resource status for the node at a rank.
- Parameters:
ctx -- reapi_cli_ctx_t context object
rank -- Single rank number, as a string e.g. "2"
status -- Pointer to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, rank not found, or unexpected internal error
Typedefs
-
typedef struct reapi_module_ctx reapi_module_ctx_t
Functions
-
reapi_module_ctx_t *reapi_module_new()
Create and initialize reapi_module context
-
void reapi_module_destroy(reapi_module_ctx_t *ctx)
Destroy reapi module context
- Parameters:
ctx -- reapi_module_ctx_t context object
-
int reapi_module_match(reapi_module_ctx_t *ctx, match_op_t match_op, const char *jobspec, const uint64_t jobid, bool *reserved, char **R, int64_t *at, double *ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
ctx -- reapi_module_ctx_t context object
match_op -- match_op_t: set to specify the specific match option from 1 of 4 choices: MATCH_ALLOCATE: try to allocate now and fail if resources aren't available. MATCH_ALLOCATE_ORELSE_RESERVE : Try to allocate and reserve if resources aren't available now. MATCH_SATISFIABILITY: Do a satisfiablity check and do not allocate. MATCH_ALLOCATE_W_SATISFIABILITY: try to allocate and run satisfiability check if resources are not available.
jobspec -- jobspec string.
jobid -- jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_module_match_allocate(reapi_module_ctx_t *ctx, bool orelse_reserve, const char *jobspec, const uint64_t jobid, bool *reserved, char **R, int64_t *at, double *ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
ctx -- reapi_module_ctx_t context object
orelse_reserve -- Boolean: if false, only allocate; otherwise, first try to allocate and if that fails, reserve.
jobspec -- jobspec string.
jobid -- jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_module_match_satisfy(reapi_module_ctx_t *ctx, const char *jobspec, double *ov)
Run Satisfiability check for jobspec.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobspec -- jobspec string.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_module_update_allocate(reapi_module_ctx_t *ctx, const uint64_t jobid, const char *R, int64_t *at, double *ov, const char **R_out)
Update the resource state with R.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- jobid of the uint64_t type.
R -- R string
at -- return the scheduled time
ov -- return the performance overhead in terms of elapse time needed to complete the match operation.
R_out -- return the updated R string.
- Returns:
0 on success; -1 on error.
-
int reapi_module_cancel(reapi_module_ctx_t *ctx, const uint64_t jobid, bool noent_ok)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- jobid of the uint64_t type.
noent_ok -- don't return an error on nonexistent jobid
- Returns:
0 on success; -1 on error.
-
int reapi_module_partial_cancel(reapi_module_ctx_t *ctx, const uint64_t jobid, const char *R, bool noent_ok, bool &full_removal)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- jobid of the uint64_t type.
R -- R string to remove
noent_ok -- don't return an error on nonexistent jobid
full_removal -- don't return an error on nonexistent jobid
- Returns:
0 on success; -1 on error.
-
int reapi_module_info(reapi_module_ctx_t *ctx, const uint64_t jobid, bool *reserved, int64_t *at, double *ov)
Get the information on the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- const jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
int reapi_module_find(reapi_module_ctx_t *ctx, const char *criteria, const char *format, char **R)
Find resources matching the criteria and return them in R format.
- Parameters:
ctx -- reapi_module_ctx_t context object
criteria -- Search criteria string (e.g., "sched-now=allocated", "status=down", etc.)
format -- Optional output format string (e.g., "rv1_nosched", "jgf"). If NULL, uses the context's configured match_format.
R -- JSON string containing matching resources in R format, or NULL if nothing matched. Caller must free with free().
- Returns:
0 on success; -1 on error (ENOSYS - not implemented).
-
int reapi_module_stat(reapi_module_ctx_t *ctx, int64_t *V, int64_t *E, int64_t *J, double *load, double *min, double *max, double *avg)
Get the performance information about the resource infrastructure.
- Parameters:
ctx -- reapi_module_ctx_t context object
V -- Number of resource vertices
E -- Number of edges
J -- Number of jobs
load -- Graph load time
min -- Min match time
max -- Max match time
avg -- Avg match time
- Returns:
0 on success; -1 on error.
-
int reapi_module_set_handle(reapi_module_ctx_t *ctx, void *handle)
Set the opaque handle to the reapi module context.
- Parameters:
ctx -- reapi_module_ctx_t context object
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
- Returns:
0 on success; -1 on error.
-
void *reapi_module_get_handle(reapi_module_ctx_t *ctx)
Set the opaque handle to the reapi module context.
- Parameters:
ctx -- reapi_module_ctx_t context object
- Returns:
handle
-
int reapi_module_set_status(reapi_module_ctx_t *ctx, const char *resource_path, resource_status_t status)
Set resource status (up or down) for a resource at the specified path.
- Parameters:
ctx -- reapi_cli_ctx_t context object
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- RESOURCE_UP or RESOURCE_DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
int reapi_module_get_status(reapi_module_ctx_t *ctx, const char *resource_path, resource_status_t *status)
Get resource status for a resource at the specified path.
- Parameters:
ctx -- reapi_module_ctx_t context object
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- Pointer to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
int reapi_module_set_rank_status(reapi_module_ctx_t *ctx, const char *ranks, resource_status_t status)
Set resource status (up or down) for all resources at each rank in a set. Unknown ranks are silently ignored.
- Parameters:
ctx -- reapi_module_ctx_t context object
ranks -- RFC 22 idset string representing a set of ranks, or "all"
status -- RESOURCE_UP or RESOURCE_DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters or unexpected internal error
-
int reapi_module_get_rank_status(reapi_module_ctx_t *ctx, const char *rank, resource_status_t *status)
Get resource status for the node at a rank.
- Parameters:
ctx -- reapi_module_ctx_t context object
rank -- Rank in string form, e.g. "2"
status -- Pointer to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, rank not found, or unexpected internal error
C++ Interface
-
namespace Flux
-
namespace resource_model
-
class queue_adapter_base_t
- #include <reapi.hpp>
Queue adapter base API class: define a set of methods a queue policy class (a subclass of this API class) must implement to be able to work with reapi_t under asynchronous execution.
Subclassed by Flux::queue_manager::queue_policy_base_t
Public Functions
-
virtual int handle_match_success(flux_jobid_t jobid, const char *status, const char *R, int64_t at, double ov) = 0
When a match succeeds, this method is called back by reapi_t with the matched resource information. The implementor (e.g., queue policy class) of this method is expected to dequeue the job from its pending queue and proceed to the next state transition.
- Parameters:
jobid -- Job ID of the uint64_t type.
status -- String indicating if the match type is allocation or reservation.
R -- Resource set: i.e., either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Match performance overhead in terms of the elapse time to complete the match operation.
- Returns:
0 on success; -1 on error.
-
virtual int handle_match_failure(flux_jobid_t jobid, int errcode) = 0
When a match failed (e.g., unsatisfiable jobspec, resource unavailable, no more jobspec to process), this method is called back by reapi_t with errcode returned from the resource match service. The implementor of this method is expected to dequeue the the job from the pending job queue, if appropriate, and proceed to the next pending job or return 0 if the scheduling loop must be terminated per its queuing policy (e.g., FCFS).
- Parameters:
errno -- returned from the resource match service. EBUSY: resource unavailable ENODEV: unsatisfiable jobspec ENODATA: no more jobspec to process Others: one that can raised from match_multi RPC
- Returns:
0 when the loop must terminate; -1 on error.
-
virtual bool is_sched_loop_active() = 0
Return true if the scheduling loop is active under asynchronous execution; otherwise false.
-
virtual int set_sched_loop_active(bool active) = 0
Set the state of the scheduling loop.
- Parameters:
active -- true when the scheduling loop becomes active; false when becomes inactive.
- Returns:
0 on success; otherwise -1 an error with errno set (Note: when the scheduling loop becomes inactive, internal queueing can occur and an error can arise):
ENOENT (job is not found from some queue)
EEXIST (enqueue fails due to an existent entry)
-
virtual int handle_match_success(flux_jobid_t jobid, const char *status, const char *R, int64_t at, double ov) = 0
-
class reapi_t
- #include <reapi.hpp>
High-level resource API base class. Derived classes must implement the methods.
Subclassed by Flux::resource_model::detail::reapi_cli_t, Flux::resource_model::detail::reapi_module_t
Public Static Functions
-
static inline int match_allocate(void *h, bool orelse_reserve, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
Match a jobspec to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
match_op -- match_op_t: set to specify the specific match option from 1 of 4 choices: MATCH_ALLOCATE: try to allocate now and fail if resources aren't available. MATCH_ALLOCATE_ORELSE_RESERVE : Try to allocate and reserve if resources aren't available now. MATCH_SATISFIABILITY: Do a satisfiablity check and do not allocate. MATCH_ALLOCATE_W_SATISFIABILITY: try to allocate and run satisfiability check if resources are not available.
jobspec -- jobspec string.
jobid -- jobid of the uint64_t type.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
R -- String into which to return the resource set either allocated or reserved.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
static int match_allocate_multi(void *h, bool orelse_reserve, const char *jobs, queue_adapter_base_t *adapter)
Multi-Match jobspecs to the "best" resources and either allocate orelse reserve them. The best resources are determined by the selected match policy.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
match_op -- match_op_t: set to specify the specific match option from 1 of 4 choices: MATCH_ALLOCATE: try to allocate now and fail if resources aren't available. MATCH_ALLOCATE_ORELSE_RESERVE : Try to allocate and reserve if resources aren't available now. MATCH_SATISFIABILITY: Do a satisfiablity check and do not allocate. MATCH_ALLOCATE_W_SATISFIABILITY: try to allocate and run
jobs -- JSON array of jobspecs.
adapter -- queue_adapter_base_t object that provides a set of callback methods to be called each time the result of a match is returned from the resource match service.
- Returns:
0 on success; -1 on error.
-
static inline int update_allocate(void *h, const uint64_t jobid, const std::string &R, int64_t &at, double &ov, std::string &R_out)
Update the resource state with R.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
jobid -- jobid of the uint64_t type.
R -- R String of std::string.
at -- return the scheduled time.
ov -- return the performance overhead in terms of elapse time needed to complete the update operation.
R_out -- return the updated R string.
- Returns:
0 on success; -1 on error.
-
static inline int add_subgraph(void *h, const std::string &R_subgraph)
Add a subgraph to the resource graph with R_subgraph.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
R_subgraph -- JGF string of subgraph to attach to existing resources. Supports adding a JGF subgraph including the path from the cluster root to the subgraph root.
- Returns:
0 on success; -1 on error.
-
static inline int remove_subgraph(void *h, const std::string &subgraph_path)
Remove a subgraph from the resource graph with subgraph_path.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
subgraph_path -- String representing the path from the cluster root to the root of the subgraph to be removed from the resource graph
- Returns:
0 on success; -1 on error.
-
static inline int cancel(void *h, const uint64_t jobid, bool noent_ok)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
jobid -- jobid of the uint64_t type.
noent_ok -- don't return an error with nonexistent jobid
- Returns:
0 on success; -1 on error.
-
static inline int cancel(void *h, const uint64_t jobid, const char *R, bool noent_ok, bool &full_removal)
Cancel the allocation or reservation corresponding to jobid.
- Parameters:
ctx -- reapi_module_ctx_t context object
jobid -- jobid of the uint64_t type.
R -- R string to remove
noent_ok -- don't return an error on nonexistent jobid
full_removal -- bool indicating whether the job is fully canceled
- Returns:
0 on success; -1 on error.
-
static int find(void *h, std::string criteria, json_t *&o, std::optional<std::string> format = std::nullopt)
Find resources matching the criteria and return them in R format.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
criteria -- Search criteria string (e.g., "sched-now=allocated", "status=down", etc.)
o -- JSON object to receive the matching resources in R format or nullptr if nothing was matched
format -- Optional output format string (e.g., "rv1_nosched", "jgf"). If std::nullopt (default), uses the context's configured match_format. If specified, creates a temporary writer for that format.
- Returns:
0 on success; -1 on error.
-
static inline int info(void *h, const uint64_t jobid, std::string &mode, bool &reserved, int64_t &at, double &ov)
Get the information on the allocation or reservation corresponding to jobid.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
jobid -- const jobid of the uint64_t type.
mode -- return string containing the job state.
reserved -- Boolean into which to return true if this job has been reserved instead of allocated.
at -- If allocated, 0 is returned; if reserved, actual time at which the job is reserved.
ov -- Double into which to return performance overhead in terms of elapse time needed to complete the match operation.
- Returns:
0 on success; -1 on error.
-
static inline int stat(void *h, int64_t &V, int64_t &E, int64_t &J, double &load, double &min, double &max, double &avg)
Get the performance information about the resource infrastructure.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
V -- Number of resource vertices
E -- Number of edges
J -- Number of jobs
load -- Graph load time
min -- Min match time
max -- Max match time
avg -- Avg match time
- Returns:
0 on success; -1 on error.
-
static int set_status(void *h, const std::string &resource_path, resource_pool_t::status_t status)
Set resource status (up or down) for a resource at the specified path.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- resource_pool_t::status_t::UP or resource_pool_t::status_t::DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
static int get_status(void *h, const std::string &resource_path, resource_pool_t::status_t &status)
Get resource status for a resource at the specified path.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
resource_path -- Path to resource (e.g., "/cluster0/rack0/node3")
status -- Reference to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, resource path not found, or unexpected internal error
-
static int set_rank_status(void *h, std::string_view ranks, resource_pool_t::status_t status)
Set resource status (up or down) for the subtree root (typically node) at each ranks in a set. Unknown ranks are silently ignored.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
ranks -- RFC 22 idset string representing a set of ranks, or "all".
status -- resource_pool_t::status_t::UP or resource_pool_t::status_t::DOWN
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters or unexpected internal error
-
static int get_rank_status(void *h, std::string_view rank, resource_pool_t::status_t &status)
Get resource status for the node at a rank.
- Parameters:
h -- Opaque handle. How it is used is an implementation detail. However, when it is used within a Flux's service module, it is expected to be a pointer to a flux_t object.
rank -- Rank number as a string, e.g. "1"
status -- Reference to receive status
- Returns:
0 on success; -1 on error with errno set: EINVAL: invalid parameters, rank not found, or unexpected internal error
-
static inline int match_allocate(void *h, bool orelse_reserve, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
class queue_adapter_base_t
-
namespace resource_model
-
namespace Flux
-
namespace resource_model
-
namespace detail
-
-
struct match_perf_t
-
struct resource_params_t
Public Members
-
std::string load_file
-
std::string load_format
-
std::string load_allowlist
-
std::string matcher_name
-
std::string matcher_policy
-
std::string traverser_policy
-
std::string o_fname
-
std::string r_fname
-
std::string o_fext
-
std::string prune_filters
-
std::string match_format
-
emit_format_t o_format
-
bool elapse_time
-
bool disable_prompt
-
bool flux_hwloc
-
size_t reserve_vtx_vec
-
std::string load_file
-
class resource_query_t
Public Functions
-
resource_query_t()
-
resource_query_t(const std::string &rgraph, const std::string &options)
-
resource_query_t(const resource_query_t &o)
-
~resource_query_t()
-
const std::string &get_resource_query_err_msg() const
-
const std::string &get_traverser_err_msg() const
-
const bool job_exists(const uint64_t jobid)
-
const uint64_t get_job_counter() const
-
const std::shared_ptr<job_info_t> &get_job(const uint64_t jobid)
-
const bool reservation_exists(const uint64_t jobid)
-
const bool allocation_exists(const uint64_t jobid)
-
const unsigned int preorder_count()
-
const unsigned int postorder_count()
-
void clear_resource_query_err_msg()
-
void clear_traverser_err_msg()
-
void set_reservation(const uint64_t jobid)
-
void erase_reservation(const uint64_t jobid)
-
void set_allocation(const uint64_t jobid)
-
void erase_allocation(const uint64_t jobid)
-
int remove_job(const uint64_t jobid)
-
int remove_job(const uint64_t jobid, const std::string &R, bool &full_removal)
-
int add_subgraph(const std::string &R_subgraph)
-
int remove_subgraph(const std::string &subgraph_path)
-
void incr_job_counter()
-
int traverser_find(std::string criteria)
-
int subsystem_exist(const std::string_view &n)
-
int set_subsystems_use(const std::string &n)
-
int set_resource_ctx_params(const std::string &options)
Public Members
-
std::shared_ptr<match_writers_t> writers
-
std::string m_err_msg
-
resource_params_t params
-
uint64_t jobid_counter
-
std::shared_ptr<dfu_match_cb_t> matcher
-
std::shared_ptr<dfu_traverser_t> traverser
-
std::shared_ptr<resource_graph_db_t> db
-
match_perf_t perf
-
std::map<uint64_t, std::shared_ptr<job_info_t>> jobs
-
std::map<uint64_t, uint64_t> allocations
-
std::map<uint64_t, uint64_t> reservations
-
resource_query_t()
-
class reapi_cli_t : public Flux::resource_model::reapi_t
Public Static Functions
-
static int match_allocate(void *h, match_op_t match_op, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
static int match_allocate_multi(void *h, bool orelse_reserve, const char *jobs, queue_adapter_base_t *adapter)
-
static int update_allocate(void *h, const uint64_t jobid, const std::string &R, int64_t &at, double &ov, std::string &R_out)
-
static int add_subgraph(void *h, const std::string &R_subgraph)
-
static int remove_subgraph(void *h, const std::string &subgraph_path)
-
static int cancel(void *h, const uint64_t jobid, bool noent_ok)
-
static int cancel(void *h, const uint64_t jobid, const std::string &R, bool noent_ok, bool &full_removal)
-
static int find(void *h, std::string criteria, json_t *&o, std::optional<std::string> format = std::nullopt)
-
static int info(void *h, const uint64_t jobid, std::string &mode, bool &reserved, int64_t &at, double &ov)
-
static unsigned int preorder_count(void *h)
-
static unsigned int postorder_count(void *h)
-
static int stat(void *h, int64_t &V, int64_t &E, int64_t &J, double &load, double &min, double &max, double &avg)
-
static int set_status(void *h, const std::string &resource_path, resource_pool_t::status_t status)
-
static int get_status(void *h, const std::string &resource_path, resource_pool_t::status_t &status)
-
static int set_rank_status(void *h, std::string_view ranks, resource_pool_t::status_t status)
-
static int get_rank_status(void *h, std::string_view rank, resource_pool_t::status_t &status)
-
static const std::string &get_err_message()
-
static void clear_err_message()
Private Static Attributes
-
static std::string m_err_msg = ""
-
static int match_allocate(void *h, match_op_t match_op, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
struct match_perf_t
-
namespace detail
-
namespace resource_model
-
namespace Flux
-
namespace resource_model
-
namespace detail
-
class reapi_module_t : public Flux::resource_model::reapi_t
Public Static Functions
-
static int match_allocate(void *h, match_op_t match_op, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
static int match_allocate(void *h, bool orelse_reserve, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
static int match_allocate_multi(void *h, bool orelse_reserve, json_t *jobs, queue_adapter_base_t *adapter)
-
static int match_allocate_multi(void *h, match_op_t match_op, json_t *jobs, queue_adapter_base_t *adapter)
-
static int update_allocate(void *h, const uint64_t jobid, const std::string &R, int64_t &at, double &ov, std::string &R_out)
-
static int cancel(void *h, const uint64_t jobid, bool noent_ok)
-
static int cancel(void *h, const uint64_t jobid, const std::string &R, bool noent_ok, bool &full_removal)
-
static int find(void *h, std::string criteria, json_t *&o, std::optional<std::string> format = std::nullopt)
-
static int info(void *h, const uint64_t jobid, bool &reserved, int64_t &at, double &ov)
-
static int stat(void *h, int64_t &V, int64_t &E, int64_t &J, double &load, double &min, double &max, double &avg)
-
static int set_status(void *h, const std::string &resource_path, resource_pool_t::status_t status)
-
static int get_status(void *h, const std::string &resource_path, resource_pool_t::status_t &status)
-
static int set_rank_status(void *h, std::string_view ranks, resource_pool_t::status_t status)
-
static int get_rank_status(void *h, std::string_view rank, resource_pool_t::status_t &status)
-
static int match_allocate(void *h, match_op_t match_op, const std::string &jobspec, const uint64_t jobid, bool &reserved, std::string &R, int64_t &at, double &ov)
-
class reapi_module_t : public Flux::resource_model::reapi_t
-
namespace detail
-
namespace resource_model