Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added gasnet documentation #6382

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/sphinx/manual.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ information on how to build and use |hpx| in different scenarios.
manual/debugging_hpx_applications
manual/optimizing_hpx_applications
manual/using_the_lci_parcelport
manual/using_the_gasnet_parcelport
manual/hpx_runtime_and_resources
manual/miscellaneous
manual/troubleshooting
68 changes: 68 additions & 0 deletions docs/sphinx/manual/using_the_gasnet_parcelport.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
..
Copyright (c) 2023 Christopher Taylor

SPDX-License-Identifier: BSL-1.0
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. _using_the_gasnet_parcelport:

===========================
Using the GASNet parcelport
===========================

.. _info_gasnet:

Basic information
=================

GASNet is a networking middleware software layer that provides support for
partitioned global address space (PGAS), remote memory access (RMA), and
active messaging (AM).

.. _`GASNet`: https://gasnet.lbl.gov

.. _build_gasnet_pp:

Build |hpx| with the GASNet parcelport
===================================

While building |hpx|, you can specify a set of |cmake| variables to enable
and configure the GASNet parcelport. Below, there is a set of the most important
and frequently used CMake variables.

.. option:: HPX_WITH_PARCELPORT_GASNET

Enable the GASNet parcelport. This enables the use of GASNet for networking operations in the |hpx| runtime.
The default value is ``OFF`` because it's not available on all systems and/or requires another dependency.
You must set this variable to ``ON`` in order to use the GASNet parcelport. All the following variables only
make sense when this variable is set to ``ON``.

.. option:: HPX_WITH_PARCELPORT_GASNET_CONDUIT

Defines which GASNet to utilize. The options are `smp;udp;mpi;ofi;ucx`. This feature tells cmake how to compile the
parcelport against a specific implementation of GASNet. The `smp` option is for single-host/rank/PE communciations,
`udp` enables GASNet udp support, `mpi` enables GASNet MPI support, `ofi` enables GASNet OpenFabrics libfabric support,
and `ucx` enables GASNet UCX support.

.. option:: HPX_WITH_FETCH_GASNET

Use FetchContent to fetch GASNet. The default value is ``OFF``.
If this option is set to ``OFF``. This feature tells |hpx| to fetch and build GASNet for you.
The compiled GASNet will use the value provided in `HPX_WITH_PARCELPORT_GASNET_CONDUIT`. This
feature requires the user to set `CMAKE_C_COMPILER`. GASNet downloaded will be installed into
`CMAKE_INSTALL_PREFIX`.

.. _run_gasnet_pp:

Run |hpx| with the GASNet parcelport
=================================

We use the same mechanisms as MPI to launch GASNet, so you can use the same way you run MPI parcelport to run GASNet
parcelport. Typically, it would be ``hpxrun``, ``amudprun``, or ``mpirun`` (for the MPI GASNet conduit).

If you are using ``hpxrun.py``, just pass ``--parcelport gasnet`` to the scripts.

If you are using ``amudprun`` or ``mpirun``, you can just pass
``--hpx:ini=hpx.parcel.gasnet.priority=1000``, ``--hpx:ini=hpx.parcel.gasnet.enable=1``, and
``--hpx:ini=hpx.parcel.bootstrap=gasnet`` to the |hpx| applications.
Loading