mca/prtedl/prtedl.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2015-2020 Cisco Systems, Inc.  All rights reserved
0004  * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
0005  *                         reserved.
0006  * Copyright (c) 2019-2020 Intel, Inc.  All rights reserved.
0007  * Copyright (c) 2021-2023 Nanook Consulting.  All rights reserved.
0008  * $COPYRIGHT$
0009  *
0010  * Additional copyrights may follow
0011  *
0012  * $HEADER$
0013  */
0014
0015 /**
0016  * @file
0017  *
0018  * Dynamic library framework
0019  *
0020  * General Description:
0021  *
0022  * This framework provides portable access to dlopen- and prtedlsym-like
0023  * functionality, very similar to Libtool's libltprtedl.  Indeed, one of
0024  * the components in this framework will use libltprtedl, if it is
0025  * present/available.  However, on some common types systems where
0026  * libltprtedl headers and libraries are *not* available, we can support
0027  * plugins via this simple framework.
0028  *
0029  * This is a compile-time framework: a single component will be
0030  * selected by the priority that its configure.m4 provides.  All other
0031  * components will be ignored (i.e., not built/not part of the
0032  * installation).  Meaning: the static_components of the prtedl framework
0033  * will always contain 0 or 1 components.
0034  *
0035  * SIDENOTE: PRTE used to embed libltprtedl.  However, as of early
0036  * 2015, this became problematic, for a variety of complex and
0037  * uninteresting reasons (see the following if you care about the
0038  * details: https://github.com/open-mpi/ompi/issues/311,
0039  * http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19370,
0040  * https://github.com/open-mpi/ompi/pull/366,
0041  * https://github.com/open-mpi/ompi/pull/390).  That being said, we,
0042  * as a developer community, still wanted to be able to natively use
0043  * DSOs by default.  A small/simple framework for DL functionality,
0044  * along with a simple component that supports dlopen/prtedlsym on POSIX
0045  * platforms and another component that natively uses libltprtedl seemed
0046  * like a good solution.
0047  */
0048
0049 #ifndef PRTE_MCA_DL_DL_H
0050 #define PRTE_MCA_DL_DL_H
0051
0052 #include "prte_config.h"
0053
0054 #include "src/pmix/pmix-internal.h"
0055 #include "src/mca/base/pmix_base.h"
0056 #include "src/mca/mca.h"
0057
0058 BEGIN_C_DECLS
0059
0060 /**
0061  * Handle for an opened file
0062  */
0063 struct prte_dl_handle_t;
0064 typedef struct prte_dl_handle_t prte_dl_handle_t;
0065
0066 /**
0067  * Dynamically open the file specified.
0068  *
0069  * Arguments:
0070  *   fname   = Base filename to open.  If NULL, open this process.
0071  *   use_ext = If true, try various filename suffixes that are
0072  *       relevant on this platform (e.g., .so, .prtedll, .dylib).  If
0073  *       false, just use exactly whatever was passed as fname.
0074  *   private = If true, open the file in a private namespace.
0075  *       Otherwise, open the file in a global namespace.
0076  *   handle = Upon successful open, a handle to the opened file will
0077  *       be returned.
0078  *   err_msg= if non-NULL and !=PRTE_SUCCESS is returned, will point to a
0079  *       string error message
0080  *
0081  * Returns:
0082  *   PRTE_SUCCESS on success, or PRTE_ERROR
0083  *
0084  * Space for the handle must be allocated by the module (it can be
0085  * freed during the call to prte_prtedl_base_module_prtedlclose_fn_t).
0086  *
0087  * The err_msg points to an internal string and should not be altered
0088  * or freed by the caller.  The contents of the err_msg string may
0089  * change after successive calls to prte_prtedl API calls.
0090  */
0091 typedef int (*prte_prtedl_base_module_open_fn_t)(const char *fname, bool use_ext,
0092                                                  bool private_namespace, prte_dl_handle_t **handle,
0093                                                  char **err_msg);
0094
0095 /**
0096  * Lookup a symbol in an opened file.
0097  *
0098  * Arguments:
0099  *   handle = handle of a previously dynamically opened file
0100  *   symbol = name of the symbol to lookup
0101  *   ptr    = if found, a pointer to the symbol.  Otherwise, NULL.
0102  *   err_msg= if non-NULL and !=PRTE_SUCCESS is returned, will point to a
0103  *            string error message
0104  * Returns:
0105  *   PRTE_SUCCESS on success, or PRTE_ERROR
0106  *
0107  *
0108  * The err_msg points to an internal string and should not be altered
0109  * or freed by the caller.  The contents of the err_msg string may
0110  * change after successive calls to prte_prtedl API calls.
0111  */
0112 typedef int (*prte_prtedl_base_module_lookup_fn_t)(prte_dl_handle_t *handle, const char *symbol,
0113                                                    void **ptr, char **err_msg);
0114
0115 /**
0116  * Dynamically close a previously dynamically-opened file.
0117  *
0118  * Arguments:
0119  *   handle = handle of a previously dynamically opened file.
0120  * Returns:
0121  *   PRTE_SUCCESS on success, or PRTE_ERROR
0122  *
0123  * This function should close the file and free and resources
0124  * associated with it (e.g., whatever is cached on the handle).
0125  */
0126 typedef int (*prte_prtedl_base_module_close_fn_t)(prte_dl_handle_t *handle);
0127
0128 /**
0129  * Search through a path of directories, invoking a callback on each
0130  * unique regular (non-Libtool) file basename found (e.g., will only
0131  * be invoked once for the files "foo.la" and "foo.so", with the
0132  * parameter "foo").
0133  *
0134  * Arguments:
0135  *   path   = PRTE_ENV_SEP-delimited list of directories
0136  *   cb_func= function to invoke on each filename found
0137  *   data   = context for callback function
0138  * Returns:
0139  *   PRTE_SUCESS on success, PRTE_ERR* otherwise
0140  */
0141 typedef int (*prte_prtedl_base_module_foreachfile_fn_t)(
0142     const char *search_path, int (*cb_func)(const char *filename, void *context), void *context);
0143
0144 /**
0145  * Structure for DL components.
0146  */
0147 struct prte_prtedl_base_component_1_0_0_t {
0148     /** MCA base component */
0149     pmix_mca_base_component_t base_version;
0150
0151     /** Default priority */
0152     int priority;
0153 };
0154 typedef struct prte_prtedl_base_component_1_0_0_t prte_prtedl_base_component_1_0_0_t;
0155 typedef struct prte_prtedl_base_component_1_0_0_t prte_prtedl_base_component_t;
0156
0157 /**
0158  * Structure for DL modules
0159  */
0160 struct prte_prtedl_base_module_1_0_0_t {
0161     pmix_mca_base_module_t super;
0162
0163     /** Open / close */
0164     prte_prtedl_base_module_open_fn_t open;
0165     prte_prtedl_base_module_close_fn_t close;
0166
0167     /** Lookup a symbol */
0168     prte_prtedl_base_module_lookup_fn_t lookup;
0169
0170     /** Iterate looking for files */
0171     prte_prtedl_base_module_foreachfile_fn_t foreachfile;
0172 };
0173 typedef struct prte_prtedl_base_module_1_0_0_t prte_prtedl_base_module_1_0_0_t;
0174 typedef struct prte_prtedl_base_module_1_0_0_t prte_prtedl_base_module_t;
0175
0176 /**
0177  * Macro for use in components that are of type DL
0178  */
0179 #define PRTE_DL_BASE_VERSION_1_0_0 PRTE_MCA_BASE_VERSION_3_0_0("prtedl", 1, 0, 0)
0180
0181 END_C_DECLS
0182
0183 #endif /* PRTE_MCA_DL_DL_H */