mca/ras/ras.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2005 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2011-2015 Los Alamos National Security, LLC.  All rights
0014  *                         reserved.
0015  * Copyright (c) 2015      Research Organization for Information Science
0016  *                         and Technology (RIST). All rights reserved.
0017  * Copyright (c) 2018-2020 Intel, Inc.  All rights reserved.
0018  * Copyright (c) 2020      Cisco Systems, Inc.  All rights reserved
0019  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0020  * $COPYRIGHT$
0021  *
0022  * Additional copyrights may follow
0023  *
0024  * $HEADER$
0025  */
0026 /** @file:
0027  *
0028  * The PRTE Resource Allocation Subsystem (RAS)
0029  *
0030  * The resource allocation subsystem is responsible for determining
0031  * what (if any) resources have been allocated to the specified job
0032  * (via some prior action), and to obtain an allocation (if possible)
0033  * if resources have NOT been previously allocated. It is anticipated
0034  * that PRTE users will execute an "mpirun" or other command that
0035  * invokes PRTE through one of two channels:
0036  *
0037  * 1. the user will login to the computing resource they intend
0038  * to use, request a resource allocation from that system, and then
0039  * execute the mpirun or other command. Thus, the allocation has
0040  * already been obtained prior to PRTE's initialization.  In most
0041  * cases, systems pass allocation information via environmental
0042  * parameters.  Thus, the RAS components must know the correct
0043  * environmental parameter to look for within the environment they
0044  * seek to support (e.g., an LSF component should know that LSF passes
0045  * allocation parameters as a specific LSF-named entity).
0046  *
0047  * 2. the user issues an mpirun command or an application that uses
0048  * PRTE without obtaining an allocation in advance. Thus, the associated
0049  * RAS component must know how to request an allocation from the
0050  * designated resource. If it doesn't, or it cannot obtain the allocation,
0051  * then it shall indicate this by setting the system to an appropriate
0052  * state.
0053  */
0054
0055 #ifndef PRTE_MCA_RAS_H
0056 #define PRTE_MCA_RAS_H
0057
0058 #include "prte_config.h"
0059 #include "constants.h"
0060 #include "types.h"
0061
0062 #include "src/class/pmix_list.h"
0063 #include "src/event/event-internal.h"
0064 #include "src/mca/mca.h"
0065 #include "src/pmix/pmix-internal.h"
0066
0067 #include "src/runtime/prte_globals.h"
0068
0069 BEGIN_C_DECLS
0070
0071 /* allocation event - the event one activates to schedule resource
0072  * allocation for pending jobs
0073  */
0074 PRTE_EXPORT extern prte_event_t prte_allocate_event;
0075
0076 /*
0077  * ras module functions - these are not accessible to the outside world,
0078  * but are defined here by convention
0079  */
0080
0081 /* init the module */
0082 typedef int (*prte_ras_base_module_init_fn_t)(void);
0083
0084 /**
0085  * Allocate resources to a job.
0086  */
0087 typedef int (*prte_ras_base_module_allocate_fn_t)(prte_job_t *jdata, pmix_list_t *nodes);
0088
0089 /* deallocate resources */
0090 typedef void (*prte_ras_base_module_dealloc_fn_t)(prte_job_t *jdata, prte_app_context_t *app);
0091
0092 /**
0093  * Cleanup module resources.
0094  */
0095 typedef int (*prte_ras_base_module_finalize_fn_t)(void);
0096
0097 /**
0098  * ras module
0099  */
0100 struct prte_ras_base_module_2_0_0_t {
0101     /** init */
0102     prte_ras_base_module_init_fn_t init;
0103     /** Allocation function pointer */
0104     prte_ras_base_module_allocate_fn_t allocate;
0105     prte_ras_base_module_dealloc_fn_t deallocate;
0106     /** Finalization function pointer */
0107     prte_ras_base_module_finalize_fn_t finalize;
0108 };
0109 /** Convenience typedef */
0110 typedef struct prte_ras_base_module_2_0_0_t prte_ras_base_module_2_0_0_t;
0111 /** Convenience typedef */
0112 typedef prte_ras_base_module_2_0_0_t prte_ras_base_module_t;
0113
0114 /*
0115  * ras component
0116  */
0117
0118 /** Convenience typedef */
0119 typedef pmix_mca_base_component_t prte_ras_base_component_t;
0120
0121 /**
0122  * Macro for use in components that are of type ras
0123  */
0124 #define PRTE_RAS_BASE_VERSION_2_0_0 PRTE_MCA_BASE_VERSION_3_0_0("ras", 2, 0, 0)
0125
0126 END_C_DECLS
0127
0128 #endif