docs: add documentation for threading tuning parameters #5917

sagarth · 2022-03-29T16:17:01Z

Pull Request Description

This PR adds documentation for tuning parameters related to multi-threading (MPI_THREAD_MULTIPLE).

Author Checklist

Provide Description
Particularly focus on why, not what. Reference background, issues, test failures, xfail entries, etc.
Commits Follow Good Practice
Commits are self-contained and do not do two things at once.
Commit message is of the form: module: short description
Commit message explains what's in the commit.
Passes All Tests
Whitespace checker. Warnings test. Additional tests via comments.
Contribution Agreement
For non-Argonne authors, check contribution agreement.
If necessary, request an explicit comment from your companies PR approval manager.

hzhou · 2022-03-29T16:19:30Z

👍 Looks good. Ping me when it is ready to review.

hzhou · 2022-03-29T17:00:42Z

doc/mpich/TUNING_PARAMETERS

+
+MPICH also supports a non-standard per-communicator info hint that provides the user with more control of a communicator-VCI mapping:
+* `vci`: Specific sender and receiver VCI can be selected for each communicator using this hint. Applications can utilize this feature to control how messages are spread across the VCIs.
+For instance, programmers can write the applications so that pairs of threads communicate by using different communicator, where each communicator can be mapped to a different VCI through the `vci` info hint. Valid values for this info hints are 0 to (total vcis - 1). This hint is also utilized by MPICH to select a progress thread to process reduction collective operation.


Could you wrap the text to width of less than 80 chars?

hzhou

It's good explanations. However, it is immediately clear for a user how to configure/tune. List configure options and cvars in separate code snippet block should help.

hzhou · 2022-03-29T18:06:07Z

doc/mpich/TUNING_PARAMETERS

+the MPI runtime, the runtime will serialize the calls. Another strategy uses a
+fine-grained lock to protect the access to each network context or VCI. With
+this approach, threads trying to access the same VCI get serialized, but threads
+accessing different VCIs can execute in parallel. With the fine-grained locking


Need explain how to configure/select between "global" and "find-grained".

I'll add the details.

hzhou · 2022-03-29T18:07:13Z

doc/mpich/TUNING_PARAMETERS

+model, MPICH supports a `direct` mode where the MPI runtime itself grabs a per
+VCI lock and a `lockless` mode where MPI does not grab a lock and relies on the
+network provider to provide fine grain synchronization (MPICH uses the
+FI_THREAD_SAFE mode from OFI to support the `lockless` mode).


Document the configure option and runtime cvars.

I'll add them.

This document will discuss various tuning parameters in MPICH.

sagarth · 2022-04-01T22:11:06Z

@hzhou I've added a fixup patch with your requested changes. Could you check if it looks fine? I'll squash it after the review.

hzhou · 2022-04-01T22:19:38Z

doc/mpich/TUNING_PARAMETERS

+A threading synchronization strategy can be selected at the configuration time
+as:
+  --enable-thread-cs=global to select coarse-grained locking, and
+  --enable-thread-cs=per-vci to select fine-grained locking.


Can you break the line so the command snippet is on its own line?

I was debating with myself about it. Sure, let me do that.

Done + squashed

hzhou

I notice you are using MARKDOWN formating throughout. How about rename this document into tuning_parameters.md and then fix the part that doesn't look right (like headings)?

I am approving it as I am OK to merge it as is. It's up to you to make additional changes. Just let me know when you are happy for it to merge.

hzhou · 2022-04-01T23:10:02Z

doc/mpich/TUNING_PARAMETERS

+https://wiki.mpich.org/mpich/index.php/Using_the_Hydra_Process_Manager#Process-core_Binding.
+
+
+


Extra empty lines.

hzhou · 2022-04-01T23:10:13Z

doc/mpich/TUNING_PARAMETERS

+
+**1. Multi-threading**
+
+


extra empty line

These are the currently supported tuning parameters for MPI_THREAD_MULTIPLE.

sagarth · 2022-04-01T23:42:08Z

Fixed the space issues. Also converted the doc file to .md and fixed some of the formatting issues. I kept the conversion on a separate patch though.

hzhou · 2022-04-01T23:43:53Z

How about add a title?

sagarth · 2022-04-01T23:54:11Z

How about add a title?

Is the how we add title to a MARKDOWN file? :
% MPICH Tuning Parameters

hzhou · 2022-04-01T23:55:13Z

How about add a title?

Is the how we add title to a MARKDOWN file? : % MPICH Tuning Parameters

Title is just bigger heading.

This is a title

Section title

This is now formatted as MARKDOWN (.md) file. This patch also fixes some of the formatting issues that appeared during the format change.

sagarth · 2022-04-01T23:58:41Z

Updated

sagarth force-pushed the upstream_threading_doc-03_22 branch from 6c360c3 to d39a3ac Compare March 29, 2022 16:17

sagarth marked this pull request as ready for review March 29, 2022 16:18

sagarth force-pushed the upstream_threading_doc-03_22 branch from d39a3ac to 8c02136 Compare March 29, 2022 16:41

hzhou requested changes Mar 29, 2022

View reviewed changes

sagarth force-pushed the upstream_threading_doc-03_22 branch 2 times, most recently from ba3fadf to f20999e Compare March 29, 2022 17:35

hzhou requested changes Mar 29, 2022

View reviewed changes

doc: Add a doc for tuning parameters

81a1db8

This document will discuss various tuning parameters in MPICH.

sagarth force-pushed the upstream_threading_doc-03_22 branch from f20999e to 38a129b Compare April 1, 2022 22:09

hzhou reviewed Apr 1, 2022

View reviewed changes

sagarth force-pushed the upstream_threading_doc-03_22 branch from 38a129b to 0241d87 Compare April 1, 2022 23:05

hzhou approved these changes Apr 1, 2022

View reviewed changes

doc: add tuning parameters for MPI_THREAD_MULTIPLE

58f272b

These are the currently supported tuning parameters for MPI_THREAD_MULTIPLE.

sagarth force-pushed the upstream_threading_doc-03_22 branch from 0241d87 to 58f272b Compare April 1, 2022 23:27

sagarth force-pushed the upstream_threading_doc-03_22 branch from 8bd5e78 to 6ddcd21 Compare April 1, 2022 23:42

doc: change format of the tuning paramerers file

3d9ed35

This is now formatted as MARKDOWN (.md) file. This patch also fixes some of the formatting issues that appeared during the format change.

sagarth force-pushed the upstream_threading_doc-03_22 branch from 6ddcd21 to 3d9ed35 Compare April 1, 2022 23:58

hzhou changed the title ~~Add documentation for threading related tuning parameters~~ docs: add documentation for threading tuning parameters Apr 2, 2022

hzhou merged commit e763458 into pmodels:main Apr 2, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add documentation for threading tuning parameters #5917

docs: add documentation for threading tuning parameters #5917

sagarth commented Mar 29, 2022 •

edited

Loading

hzhou commented Mar 29, 2022

hzhou Mar 29, 2022

sagarth Mar 29, 2022

hzhou left a comment

hzhou Mar 29, 2022

sagarth Mar 31, 2022

sagarth Apr 1, 2022

hzhou Mar 29, 2022

sagarth Mar 31, 2022

sagarth Apr 1, 2022

sagarth commented Apr 1, 2022

hzhou Apr 1, 2022

sagarth Apr 1, 2022

sagarth Apr 1, 2022 •

edited

Loading

hzhou left a comment

hzhou Apr 1, 2022

hzhou Apr 1, 2022

sagarth commented Apr 1, 2022

hzhou commented Apr 1, 2022

sagarth commented Apr 1, 2022

hzhou commented Apr 1, 2022

sagarth commented Apr 1, 2022

		https://wiki.mpich.org/mpich/index.php/Using_the_Hydra_Process_Manager#Process-core_Binding.


		1. Multi-threading

docs: add documentation for threading tuning parameters #5917

docs: add documentation for threading tuning parameters #5917

Conversation

sagarth commented Mar 29, 2022 • edited Loading

Pull Request Description

Author Checklist

hzhou commented Mar 29, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hzhou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sagarth commented Apr 1, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sagarth Apr 1, 2022 • edited Loading

Choose a reason for hiding this comment

hzhou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sagarth commented Apr 1, 2022

hzhou commented Apr 1, 2022

sagarth commented Apr 1, 2022

hzhou commented Apr 1, 2022

This is a title

Section title

sagarth commented Apr 1, 2022

sagarth commented Mar 29, 2022 •

edited

Loading

sagarth Apr 1, 2022 •

edited

Loading