mca/pdl/pdl.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2015 Cisco Systems, Inc.  All rights reserved.
0004  * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
0005  *                         reserved.
0006  * Copyright (c) 2020      Intel, Inc.  All rights reserved.
0007  * Copyright (c) 2021-2022 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 dlsym-like
0023  * functionality, very similar to Libtool's libltdl.  Indeed, one of
0024  * the components in this framework will use libltdl, if it is
0025  * present/available.  However, on some common types systems where
0026  * libltdl 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 pdl framework
0033  * will always contain 0 or 1 components.
0034  *
0035  * SIDENOTE: PMIX used to embed libltdl.  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 PDL functionality,
0044  * along with a simple component that supports dlopen/dlsym on POSIX
0045  * platforms and another component that natively uses libltdl seemed
0046  * like a good solution.
0047  */
0048
0049 #ifndef PMIX_MCA_PDL_PDL_H
0050 #define PMIX_MCA_PDL_PDL_H
0051
0052 #include "src/include/pmix_config.h"
0053
0054 #include "src/mca/base/pmix_base.h"
0055 #include "src/mca/mca.h"
0056
0057 BEGIN_C_DECLS
0058
0059 /**
0060  * Handle for an opened file
0061  */
0062 struct pmix_pdl_handle_t;
0063 typedef struct pmix_pdl_handle_t pmix_pdl_handle_t;
0064
0065 /**
0066  * Dynamically open the file specified.
0067  *
0068  * Arguments:
0069  *   fname   = Base filename to open.  If NULL, open this process.
0070  *   use_ext = If true, try various filename suffixes that are
0071  *       relevant on this platform (e.g., .so, .dll, .dylib).  If
0072  *       false, just use exactly whatever was passed as fname.
0073  *   private = If true, open the file in a private namespace.
0074  *       Otherwise, open the file in a global namespace.
0075  *   handle = Upon successful open, a handle to the opened file will
0076  *       be returned.
0077  *   err_msg= if non-NULL and !=PMIX_SUCCESS is returned, will point to a
0078  *       string error message
0079  *
0080  * Returns:
0081  *   PMIX_SUCCESS on success, or PMIX_ERROR
0082  *
0083  * Space for the handle must be allocated by the module (it can be
0084  * freed during the call to pmix_pdl_base_module_dlclose_fn_t).
0085  *
0086  * The err_msg points to an internal string and should not be altered
0087  * or freed by the caller.  The contents of the err_msg string may
0088  * change after successive calls to pmix_pdl API calls.
0089  */
0090 typedef int (*pmix_pdl_base_module_open_fn_t)(const char *fname, bool use_ext,
0091                                               bool private_namespace, pmix_pdl_handle_t **handle,
0092                                               char **err_msg);
0093
0094 /**
0095  * Lookup a symbol in an opened file.
0096  *
0097  * Arguments:
0098  *   handle = handle of a previously dynamically opened file
0099  *   symbol = name of the symbol to lookup
0100  *   ptr    = if found, a pointer to the symbol.  Otherwise, NULL.
0101  *   err_msg= if non-NULL and !=PMIX_SUCCESS is returned, will point to a
0102  *            string error message
0103  * Returns:
0104  *   PMIX_SUCCESS on success, or PMIX_ERROR
0105  *
0106  *
0107  * The err_msg points to an internal string and should not be altered
0108  * or freed by the caller.  The contents of the err_msg string may
0109  * change after successive calls to pmix_pdl API calls.
0110  */
0111 typedef int (*pmix_pdl_base_module_lookup_fn_t)(pmix_pdl_handle_t *handle, const char *symbol,
0112                                                 void **ptr, char **err_msg);
0113
0114 /**
0115  * Dynamically close a previously dynamically-opened file.
0116  *
0117  * Arguments:
0118  *   handle = handle of a previously dynamically opened file.
0119  * Returns:
0120  *   PMIX_SUCCESS on success, or PMIX_ERROR
0121  *
0122  * This function should close the file and free and resources
0123  * associated with it (e.g., whatever is cached on the handle).
0124  */
0125 typedef int (*pmix_pdl_base_module_close_fn_t)(pmix_pdl_handle_t *handle);
0126
0127 /**
0128  * Search through a path of directories, invoking a callback on each
0129  * unique regular (non-Libtool) file basename found (e.g., will only
0130  * be invoked once for the files "foo.la" and "foo.so", with the
0131  * parameter "foo").
0132  *
0133  * Arguments:
0134  *   path   = PMIX_ENV_SEP-delimited list of directories
0135  *   cb_func= function to invoke on each filename found
0136  *   data   = context for callback function
0137  * Returns:
0138  *   PMIX_SUCESS on success, PMIX_ERR* otherwise
0139  */
0140 typedef int (*pmix_pdl_base_module_foreachfile_fn_t)(
0141     const char *search_path, int (*cb_func)(const char *filename, void *context), void *context);
0142
0143 /**
0144  * Structure for PDL components.
0145  */
0146 struct pmix_pdl_base_component_1_0_0_t {
0147     /** MCA base component */
0148     pmix_mca_base_component_t base_version;
0149     /** Default priority */
0150     int priority;
0151 };
0152 typedef struct pmix_pdl_base_component_1_0_0_t pmix_pdl_base_component_1_0_0_t;
0153 typedef struct pmix_pdl_base_component_1_0_0_t pmix_pdl_base_component_t;
0154
0155 /**
0156  * Structure for PDL modules
0157  */
0158 struct pmix_pdl_base_module_1_0_0_t {
0159     pmix_mca_base_module_2_0_0_t super;
0160
0161     /** Open / close */
0162     pmix_pdl_base_module_open_fn_t open;
0163     pmix_pdl_base_module_close_fn_t close;
0164
0165     /** Lookup a symbol */
0166     pmix_pdl_base_module_lookup_fn_t lookup;
0167
0168     /** Iterate looking for files */
0169     pmix_pdl_base_module_foreachfile_fn_t foreachfile;
0170 };
0171 typedef struct pmix_pdl_base_module_1_0_0_t pmix_pdl_base_module_1_0_0_t;
0172 typedef struct pmix_pdl_base_module_1_0_0_t pmix_pdl_base_module_t;
0173
0174 /**
0175  * Macro for use in components that are of type PDL
0176  */
0177 #define PMIX_PDL_BASE_VERSION_1_0_0 PMIX_MCA_BASE_VERSION_1_0_0("pdl", 1, 0, 0)
0178
0179 END_C_DECLS
0180
0181 #endif /* PMIX_MCA_PDL_PDL_H */