.. _man3-PMIx_server_init: PMIx_server_init ================ .. include_body ``PMIx_server_init`` |mdash| Initialize the PMIx server support library. SYNOPSIS -------- .. code-block:: c #include pmix_status_t PMIx_server_init(pmix_server_module_t *module, pmix_info_t info[], size_t ninfo); Python Syntax ^^^^^^^^^^^^^ .. code-block:: python3 from pmix import * foo = PMIxServer() # the directives is a list of Python ``pmix_info_t`` dictionaries pydirs = [{'key': PMIX_SERVER_NSPACE, 'value': {'value': "SERVER", 'val_type': PMIX_STRING}}] # map is a dictionary of server-module-function keys to Python # callback implementations (e.g. {'clientconnected': myconnfn, ...}) rc = foo.init(pydirs, map) INPUT PARAMETERS ---------------- * ``module``: Pointer to a :ref:`pmix_server_module_t(5) ` structure containing the host environment's callback functions |mdash| the "function-shipped" server module through which client requests are relayed to the resource manager. Any function the host does not support is indicated by leaving its function pointer ``NULL``; client calls to an unsupported operation return a "not supported" error. Passing ``NULL`` for ``module`` (or an empty structure) is permitted and indicates that the host will not support multi-node operations such as :ref:`PMIx_Fence(3) `, but still intends to give local clients access to job information. * ``info``: Pointer to an array of :ref:`pmix_info_t(5) ` structures conveying directives that qualify server initialization (see `DIRECTIVES`_). A ``NULL`` value is supported when no directives are desired. * ``ninfo``: Number of elements in the ``info`` array. DESCRIPTION ----------- Initialize the PMIx server support library and register the host environment's callback module. ``PMIx_server_init`` is called by the process that hosts the PMIx server |mdash| typically a resource manager daemon, launcher, or tool that will accept client and/or tool connections. The PMIx server provides a *function-shipping* approach to the server side of the protocol: each client-visible PMIx operation is mirrored by an entry in the ``pmix_server_module_t`` structure. When a client request arrives, the PMIx server library invokes the corresponding host function so that resource managers can implement server behavior without being burdened with PMIx internal details. For performance and scalability, host module functions are required to return quickly and to execute their work asynchronously, completing each operation by invoking the callback function supplied to them. Ownership rules for the module functions are important: all data passed *to* a host server function is owned by the PMIx server library and must not be freed by the host, while data returned by the host via a module callback is owned by the host and may be released once the callback returns. The ``info`` array supplies additional information the server may need when initializing |mdash| for example, the namespace and rank to assign to the server itself, the temporary directory in which to place the rendezvous socket, or the ``PMIX_SERVER_TOOL_SUPPORT`` directive announcing that the daemon is willing to accept connection requests from tools (see `DIRECTIVES`_). The PMIx server library is reference counted. Repeated calls to ``PMIx_server_init`` are permitted and simply increment the reference count; if a ``module`` is provided on a later call and none had been set previously, the library adopts it. Each successful call must be balanced by a matching call to :ref:`PMIx_server_finalize(3) `. ``PMIx_server_init`` is a blocking call that completes synchronously; it does not take a callback. DIRECTIVES ---------- The following attributes are relevant to this operation. Support for any given attribute is optional and depends on how the PMIx implementation was built and on the capabilities of the host environment. All are passed in the ``info`` array. Server identity and directories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``PMIX_SERVER_NSPACE`` (char\*) |mdash| namespace to assign to this PMIx server. * ``PMIX_SERVER_RANK`` (pmix_rank_t) |mdash| rank to assign to this PMIx server. * ``PMIX_SERVER_TMPDIR`` (char\*) |mdash| temporary directory in which the server is to place client rendezvous points and contact information. * ``PMIX_SYSTEM_TMPDIR`` (char\*) |mdash| temporary directory in which the server is to place tool rendezvous points and system-level contact information. Role and support attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``PMIX_SERVER_TOOL_SUPPORT`` (bool) |mdash| the host is willing to accept connection requests from tools. * ``PMIX_SERVER_SYSTEM_SUPPORT`` (bool) |mdash| the host is willing to accept connections from system-level tools (a system-level rendezvous point is established). * ``PMIX_SERVER_SESSION_SUPPORT`` (bool) |mdash| the host is willing to accept connections from session-level tools. * ``PMIX_SERVER_GATEWAY`` (bool) |mdash| the server is acting as a gateway that can relay operations (e.g., logging) requiring routing to other nodes. * ``PMIX_SERVER_SCHEDULER`` (bool) |mdash| the server is hosting the system scheduler (workload manager) and expects to receive scheduler-related requests. * ``PMIX_SERVER_SYS_CONTROLLER`` (bool) |mdash| the server is hosting the system controller. * ``PMIX_SERVER_REMOTE_CONNECTIONS`` (bool) |mdash| allow (or disable) connections from remote tools. * ``PMIX_SERVER_ALLOW_FOREIGN_TOOLS`` (bool) |mdash| mark the tool rendezvous files as readable by all users and allow tools running under user IDs other than that of the server to connect. The host retains ultimate authority over such connections and may restrict what foreign tools are permitted to do (for example, limiting them to queries) as dictated by host policy. * ``PMIX_ALLOW_CLIENT_CLONES`` (bool) |mdash| allow connections from clones (forks) of a registered client process. Topology and behavior attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``PMIX_TOPOLOGY2`` (pmix_topology_t) |mdash| pointer to an implementation-specific description of the local node topology. * ``PMIX_SERVER_SHARE_TOPOLOGY`` (bool) |mdash| the server is to scalably expose the node topology to its local clients (for example, via shared-memory backing stores), cleaning up any artifacts at finalize. * ``PMIX_HOMOGENEOUS_SYSTEM`` (bool) |mdash| the nodes in the system are topologically identical, so the server need not compute or exchange per-node topology descriptions. * ``PMIX_SERVER_ENABLE_MONITORING`` (bool) |mdash| enable the internal monitoring capabilities of the PMIx server. * ``PMIX_EXTERNAL_PROGRESS`` (bool) |mdash| the host will progress the PMIx library as needed via calls to ``PMIx_Progress`` rather than PMIx spawning its own internal progress thread. * ``PMIX_SINGLETON`` (char\*) |mdash| the server is operating in support of a singleton process; the value is the ``nspace.rank`` string of that singleton. * ``PMIX_IOF_LOCAL_OUTPUT`` (bool) |mdash| write output streams to the server's own stdout/stderr. * ``PMIX_BIND_PROGRESS_THREAD`` (char\*) |mdash| comma-delimited ranges of CPUs to which the internal PMIx progress thread is to be bound. * ``PMIX_BIND_REQUIRED`` (bool) |mdash| return an error if the internal PMIx progress thread cannot be bound as requested. * ``PMIX_EXTERNAL_AUX_EVENT_BASE`` (void\*) |mdash| pointer to an ``event_base`` the library is to use for auxiliary functions (e.g., capturing signals) that would otherwise interfere with the host. RETURN VALUE ------------ Returns ``PMIX_SUCCESS`` on success. On error, a negative value corresponding to a PMIx error constant is returned, including: * ``PMIX_ERR_INIT`` |mdash| the PMIx server library could not be initialized (for example, a required transport was explicitly disabled, or a tight race between concurrent ``PMIx_server_init`` calls left the library in an unusable state). * ``PMIX_ERR_NOT_SUPPORTED`` |mdash| a provided directive requested behavior the implementation does not support. Any other negative value indicates an appropriate error condition. PMIx error constants are defined in ``pmix_common.h``. NOTES ----- ``PMIx_server_init`` is intended for use only by processes acting as a PMIx *server* |mdash| processes that host the server support library on behalf of a resource manager or launcher. Client processes call :ref:`PMIx_Init(3) ` and tools call :ref:`PMIx_tool_init(3) ` instead. After a successful ``PMIx_server_init``, the host is expected to register each participating namespace with :ref:`PMIx_server_register_nspace(3) ` and each local client with :ref:`PMIx_server_register_client(3) ` before launching that client, then set up the client's environment with ``PMIx_server_setup_fork``. .. seealso:: :ref:`PMIx_server_finalize(3) `, :ref:`PMIx_server_register_nspace(3) `, :ref:`PMIx_server_register_client(3) `, :ref:`PMIx_Init(3) `, :ref:`PMIx_tool_init(3) `, :ref:`pmix_server_module_t(5) `, :ref:`pmix_info_t(5) `, :ref:`pmix_status_t(5) `