How does the "complete" option in mpp_update_domains work?

[TingLei-NOAA]

Hi, folks,
Thanks a lot in advance for any comments/suggestions on my question raised here.
Two main systems I am working with : JEDI and UFS are both dependent on FMS.
Recently, I spent quite some time and am still confused on the use of the optional argument "complete" in the mpp_update_domains sub.
From reading around (including the lecture https://data1.gfdl.noaa.gov/summer-school/Lectures/July17/02_Jeff1_HaloUpdates-Final.pdf) , it seems this argument control whether mpp_update_domains is run in a blocking (complete=.true.) or non-blocking mode (complete=.false.).
However, looking at the subroutine itself in /mpp_update_domains2D.h,
it looks to me , when complete=.false., it would let do_update=.false.,
and the program would not run the following essential part around "mpp_do_update".
Namely, in my understanding, when complete=.false., the halo-update proces hasn't been carried out at all. So, I have to miss something. However,
After spending quite some time, I still failed to find the machinery for use of complete=.false.,
Would you please let me know how the "complete" option works ?
Your help is appreciated.

[bensonr]

The 'complete' argument for the many mpp_* functions within the FMS communication infrastructure layer is used a signal to determine when the actual communication occurs. When complete=.false., the function in question is merely buffering the data and waiting until the complete flag is set to .true. to perform the actual communication.

For example, if one needs to share or communicate a number of variables with neighbors, say pressure, temperature, and six condensate tracers, the traditional method would result in eight separate MPI messages - one for each variable. As an FMS communication optimization, setting complete=.false. for the first seven merely results in the variable and data being registered with control returned to the application. The eighth, and final communication, sets complete=.true. which would signal the function that it is ready to finalize the buffer and communicate the entirety of the buffered data in a single MPI message. If one were doing a halo update, the complete=.true. is the point where the halo regions all eight variables would be updated.

One word of caution, you can't mix and match the update position type within the complete hierarchy.

For asynchronous communication of halo updates, there are a series of mpp functions with group_update in the name that can be used to create groups, start a group update, and perform or query for completion. If desired, examples of the uses of the asynchronous communication groups can be provided.

[TingLei-NOAA]

@bensonr Thank you so much for your clear explanation, which reveals what I missed in the whole process (registering/ all 8 variables be updated in the final call, in the example). Now, I understand it in a much better position.
Really appreciate your help!
Ting