Whamcloud - gitweb
LU-9078 lnet: Fix route hops print
[fs/lustre-release.git] / lnet / doc / portals3.lyx
1 #LyX 1.2 created this file. For more info see http://www.lyx.org/
2 \lyxformat 220
3 \textclass report
4 \begin_preamble
5 \usepackage{fullpage}
6 \renewenvironment{comment}%
7 {\begin{quote}\textbf{Discussion}: \slshape}%
8 {\end{quote}}
9 \pagestyle{myheadings}
10 \end_preamble
11 \language american
12 \inputencoding auto
13 \fontscheme pslatex
14 \graphics default
15 \paperfontsize 10
16 \spacing single 
17 \papersize letterpaper
18 \paperpackage a4
19 \use_geometry 0
20 \use_amsmath 0
21 \use_natbib 0
22 \use_numerical_citations 0
23 \paperorientation portrait
24 \secnumdepth 2
25 \tocdepth 2
26 \paragraph_separation indent
27 \defskip medskip
28 \quotes_language english
29 \quotes_times 2
30 \papercolumns 1
31 \papersides 2
32 \paperpagestyle headings
33
34 \layout Title
35
36 The Portals 3.2 Message Passing Interface 
37 \newline 
38  Revision 1.1
39 \layout Author
40
41 Ron Brightwell
42 \begin_inset Foot
43 collapsed true
44
45 \layout Standard
46
47 R.
48  Brightwell and R.
49  Riesen are with the Scalable Computing Systems Department, Sandia National
50  Laboratories, P.O.
51  Box 5800, Albuquerque, NM\SpecialChar ~
52 \SpecialChar ~
53 87111-1110, bright@cs.sandia.gov, rolf@cs.sandia.gov.
54 \end_inset 
55
56 , Arthur B.
57  Maccabe
58 \begin_inset Foot
59 collapsed true
60
61 \layout Standard
62
63 A.
64  B.
65  Maccabe is with the Computer Science Department, University of New Mexico,
66  Albuquerque, NM\SpecialChar ~
67 \SpecialChar ~
68 87131-1386, maccabe@cs.unm.edu.
69 \end_inset 
70
71 , Rolf Riesen and Trammell Hudson
72 \layout Abstract
73
74 This report presents a specification for the Portals 3.2 message passing
75  interface.
76  Portals 3.2 is intended to allow scalable, high-performance network communicatio
77 n between nodes of a parallel computing system.
78  Specifically, it is designed to support a parallel computing platform composed
79  of clusters of commodity workstations connected by a commodity system area
80  network fabric.
81  In addition, Portals 3.2 is well suited to massively parallel processing
82  and embedded systems.
83  Portals 3.2 represents an adaption of the data movement layer developed
84  for massively parallel processing platforms, such as the 4500-node Intel
85  TeraFLOPS machine.
86  
87 \layout Standard
88
89
90 \begin_inset ERT
91 status Collapsed
92
93 \layout Standard
94
95 \backslash 
96 clearpage
97 \backslash 
98 pagenumbering{roman}
99 \backslash 
100 setcounter{page}{3}
101 \end_inset 
102
103
104 \layout Standard
105
106
107 \begin_inset LatexCommand \tableofcontents{}
108
109 \end_inset 
110
111
112 \layout Standard
113
114
115 \begin_inset ERT
116 status Collapsed
117
118 \layout Standard
119
120 \backslash 
121 cleardoublepage
122 \end_inset 
123
124
125 \layout Standard
126
127
128 \begin_inset FloatList figure
129
130 \end_inset 
131
132
133 \layout Standard
134
135
136 \begin_inset ERT
137 status Collapsed
138
139 \layout Standard
140
141 \backslash 
142 cleardoublepage
143 \end_inset 
144
145
146 \layout Standard
147
148
149 \begin_inset FloatList table
150
151 \end_inset 
152
153
154 \layout Standard
155
156
157 \begin_inset ERT
158 status Collapsed
159
160 \layout Standard
161
162 \backslash 
163 cleardoublepage
164 \end_inset 
165
166
167 \layout Chapter*
168
169 Summary of Changes for Revision 1.1
170 \layout Enumerate
171
172 Updated version number to 3.2 throughout the document
173 \layout Enumerate
174
175 Section 
176 \begin_inset LatexCommand \ref{sub:PtlGetId}
177
178 \end_inset 
179
180 : added 
181 \family typewriter 
182 PTL_SEGV
183 \family default 
184  to error list for 
185 \shape italic 
186 PtlGetId
187 \shape default 
188 .
189 \layout Enumerate
190
191 Section 
192 \begin_inset LatexCommand \ref{sec:meattach}
193
194 \end_inset 
195
196 : added 
197 \family typewriter 
198 PTL_ML_TOOLONG
199 \family default 
200  to error list for 
201 \shape italic 
202 PtlMEAttach
203 \shape default 
204 .
205 \layout Enumerate
206
207 Section 
208 \begin_inset LatexCommand \ref{sec:meunlink}
209
210 \end_inset 
211
212 : removed text referring to a list of associated memory descriptors.
213 \layout Enumerate
214
215 Section 
216 \begin_inset LatexCommand \ref{sec:mdfree}
217
218 \end_inset 
219
220 : added text to describe unlinking a free-floating memory descriptor.
221 \layout Enumerate
222
223 Table 
224 \begin_inset LatexCommand \ref{tab:types}
225
226 \end_inset 
227
228 : added entry for 
229 \family typewriter 
230 ptl_seq_t
231 \family default 
232 .
233 \layout Enumerate
234
235 Section 
236 \begin_inset LatexCommand \ref{sec:md-type}
237
238 \end_inset 
239
240 :
241 \begin_deeper 
242 \layout Enumerate
243
244 added definition of 
245 \family typewriter 
246 max_offset
247 \family default 
248 .
249 \layout Enumerate
250
251 added text to clarify 
252 \family typewriter 
253 PTL_MD_MANAGE_REMOTE
254 \family default 
255 .
256 \end_deeper 
257 \layout Enumerate
258
259 Section 
260 \begin_inset LatexCommand \ref{sec:mdattach}
261
262 \end_inset 
263
264 : modified text for 
265 \family typewriter 
266 unlink_op
267 \family default 
268 .
269 \layout Enumerate
270
271 Section 
272 \begin_inset LatexCommand \ref{sec:niinit}
273
274 \end_inset 
275
276 : added text to clarify multiple calls to 
277 \shape italic 
278 PtlNIInit
279 \shape default 
280 .
281 \layout Enumerate
282
283 Section 
284 \begin_inset LatexCommand \ref{sec:mdattach}
285
286 \end_inset 
287
288 : added text to clarify 
289 \family typewriter 
290 unlink_nofit
291 \family default 
292 .
293 \layout Enumerate
294
295 Section 
296 \begin_inset LatexCommand \ref{sec:receiving}
297
298 \end_inset 
299
300 : removed text indicating that an MD will reject a message if the associated
301  EQ is full.
302 \layout Enumerate
303
304 Section 
305 \begin_inset LatexCommand \ref{sec:mdfree}
306
307 \end_inset 
308
309 : added 
310 \family typewriter 
311 PTL_MD_INUSE
312 \family default 
313  error code and text to indicate that only MDs with no pending operations
314  can be unlinked.
315 \layout Enumerate
316
317 Table 
318 \begin_inset LatexCommand \ref{tab:retcodes}
319
320 \end_inset 
321
322 : added 
323 \family typewriter 
324 PTL_MD_INUSE
325 \family default 
326  return code.
327 \layout Enumerate
328
329 Section 
330 \begin_inset LatexCommand \ref{sec:event-type}
331
332 \end_inset 
333
334 : added user id field, MD handle field, and NI specific failure field to
335  the 
336 \family typewriter 
337 ptl_event_t
338 \family default 
339  structure.
340 \layout Enumerate
341
342 Table 
343 \begin_inset LatexCommand \ref{tab:types}
344
345 \end_inset 
346
347 : added 
348 \family typewriter 
349 ptl_ni_fail_t
350 \family default 
351 .
352 \layout Enumerate
353
354 Section 
355 \begin_inset LatexCommand \ref{sec:event-type}
356
357 \end_inset 
358
359 : added 
360 \family typewriter 
361 PTL_EVENT_UNLINK
362 \family default 
363  event type.
364 \layout Enumerate
365
366 Table 
367 \begin_inset LatexCommand \ref{tab:func}
368
369 \end_inset 
370
371 : removed 
372 \shape slanted 
373 PtlTransId
374 \shape default 
375 .
376 \layout Enumerate
377
378 Section 
379 \begin_inset LatexCommand \ref{sec:meattach}
380
381 \end_inset 
382
383 , Section 
384 \begin_inset LatexCommand \ref{sec:meinsert}
385
386 \end_inset 
387
388 , Section 
389 \begin_inset LatexCommand \ref{sec:put}
390
391 \end_inset 
392
393 : listed allowable constants with relevant fields.
394 \layout Enumerate
395
396 Table 
397 \begin_inset LatexCommand \ref{tab:func}
398
399 \end_inset 
400
401 : added 
402 \shape italic 
403 PtlMEAttachAny
404 \shape default 
405  function.
406 \layout Enumerate
407
408 Table 
409 \begin_inset LatexCommand \ref{tab:retcodes}
410
411 \end_inset 
412
413 : added 
414 \family typewriter 
415 PTL_PT_FULL
416 \family default 
417  return code for 
418 \shape italic 
419 PtlMEAttachAny
420 \shape default 
421 .
422 \layout Enumerate
423
424 Table 
425 \begin_inset LatexCommand \ref{tab:oconsts}
426
427 \end_inset 
428
429 : updated to reflect new event types.
430 \layout Enumerate
431
432 Section 
433 \begin_inset LatexCommand \ref{sec:id-type}
434
435 \end_inset 
436
437 : added 
438 \family typewriter 
439 ptl_nid_t
440 \family default 
441
442 \family typewriter 
443 ptl_pid_t
444 \family default 
445 , and 
446 \family typewriter 
447 ptl_uid_t
448 \family default 
449 .
450 \layout Chapter*
451
452 Summary of Changes for Version 3.1
453 \layout Section*
454
455 Thread Issues
456 \layout Standard
457
458 The most significant change to the interface from version 3.0 to 3.1 involves
459  the clarification of how the interface interacts with multi-threaded applicatio
460 ns.
461  We adopted a generic thread model in which processes define an address
462  space and threads share the address space.
463  Consideration of the API in the light of threads lead to several clarifications
464  throughout the document: 
465 \layout Enumerate
466
467 Glossary: 
468 \begin_deeper 
469 \layout Enumerate
470
471 added a definition for 
472 \emph on 
473 thread
474 \emph default 
475
476 \layout Enumerate
477
478 reworded the definition for 
479 \emph on 
480 process
481 \emph default 
482 .
483  
484 \end_deeper 
485 \layout Enumerate
486
487 Section\SpecialChar ~
488
489 \begin_inset LatexCommand \ref{sec:apiover}
490
491 \end_inset 
492
493 : added section\SpecialChar ~
494
495 \begin_inset LatexCommand \ref{sec:threads}
496
497 \end_inset 
498
499  to describe the multi-threading model used by the Portals API.
500  
501 \layout Enumerate
502
503 Section\SpecialChar ~
504
505 \begin_inset LatexCommand \ref{sec:ptlinit}
506
507 \end_inset 
508
509
510 \emph on 
511 PtlInit
512 \emph default 
513  must be called at least once and may be called any number of times.
514  
515 \layout Enumerate
516
517 Section\SpecialChar ~
518
519 \begin_inset LatexCommand \ref{sec:ptlfini}
520
521 \end_inset 
522
523
524 \emph on 
525 PtlFini
526 \emph default 
527  should be called once as the process is terminating and not as each thread
528  terminates.
529  
530 \layout Enumerate
531
532 Section\SpecialChar ~
533
534 \begin_inset LatexCommand \ref{sec:pid}
535
536 \end_inset 
537
538 : Portals does not define thread ids.
539  
540 \layout Enumerate
541
542 Section\SpecialChar ~
543
544 \begin_inset LatexCommand \ref{sec:ni}
545
546 \end_inset 
547
548 : network interfaces are associated with processes, not threads.
549  
550 \layout Enumerate
551
552 Section\SpecialChar ~
553
554 \begin_inset LatexCommand \ref{sec:niinit}
555
556 \end_inset 
557
558
559 \emph on 
560 PtlNIInit
561 \emph default 
562  must be called at least once and may be called any number of times.
563  
564 \layout Enumerate
565
566 Section\SpecialChar ~
567
568 \begin_inset LatexCommand \ref{sec:eqget}
569
570 \end_inset 
571
572
573 \emph on 
574 PtlEQGet
575 \emph default 
576  returns 
577 \family typewriter 
578 PTL_EQ_EMPTY
579 \family default 
580  if a thread is blocked on 
581 \emph on 
582 PtlEQWait
583 \emph default 
584 .
585  
586 \layout Enumerate
587
588 Section\SpecialChar ~
589
590 \begin_inset LatexCommand \ref{sec:eqwait}
591
592 \end_inset 
593
594 : waiting threads are awakened in FIFO order.
595  
596 \layout Standard
597
598 Two functions, 
599 \emph on 
600 PtlNIBarrier
601 \emph default 
602  and 
603 \emph on 
604 PtlEQCount
605 \emph default 
606  were removed from the API.
607  
608 \emph on 
609 PtlNIBarrier
610 \emph default 
611  was defined to block the calling process until all of the processes in
612  the application group had invoked 
613 \emph on 
614 PtlNIBarrier
615 \emph default 
616 .
617  We now consider this functionality, along with the concept of groups (see
618  the discussion under 
619 \begin_inset Quotes eld
620 \end_inset 
621
622 other changes
623 \begin_inset Quotes erd
624 \end_inset 
625
626 ), to be part of the runtime system, not part of the Portals API.
627  
628 \emph on 
629 PtlEQCount
630 \emph default 
631  was defined to return the number of events in an event queue.
632  Because external operations may lead to new events being added and other
633  threads may remove events, the value returned by 
634 \emph on 
635 PtlEQCount
636 \emph default 
637  would have to be a hint about the number of events in the event queue.
638 \layout Section*
639
640 Handling small, unexpected messages
641 \layout Standard
642
643 Another set of changes relates to handling small unexpected messages in
644  MPI.
645  In designing version 3.0, we assumed that each unexpected message would
646  be placed in a unique memory descriptor.
647  To avoid the need to process a long list of memory descriptors, we moved
648  the memory descriptors out of the match list and hung them off of a single
649  match list entry.
650  In this way, large unexpected messages would only encounter a single 
651 \begin_inset Quotes eld
652 \end_inset 
653
654 short message
655 \begin_inset Quotes erd
656 \end_inset 
657
658  match list entry before encountering the 
659 \begin_inset Quotes eld
660 \end_inset 
661
662 long message
663 \begin_inset Quotes erd
664 \end_inset 
665
666  match list entry.
667  Experience with this strategy identified resource management problems with
668  this approach.
669  In particular, a long sequence of very short (or zero length) messages
670  could quickly exhaust the memory descriptors constructed for handling unexpecte
671 d messages.
672  Our new strategy involves the use of several very large memory descriptors
673  for small unexpected messages.
674  Consecutive unexpected messages will be written into the first of these
675  memory descriptors until the memory descriptor fills up.
676  When the first of the 
677 \begin_inset Quotes eld
678 \end_inset 
679
680 small memory
681 \begin_inset Quotes erd
682 \end_inset 
683
684  descriptors fills up, it will be unlinked and subsequent short messages
685  will be written into the next 
686 \begin_inset Quotes eld
687 \end_inset 
688
689 short message
690 \begin_inset Quotes erd
691 \end_inset 
692
693  memory descriptor.
694  In this case, a 
695 \begin_inset Quotes eld
696 \end_inset 
697
698 short message
699 \begin_inset Quotes erd
700 \end_inset 
701
702  memory descriptor will be declared full when it does not have sufficient
703  space for the largest small unexpected message.
704 \layout Standard
705
706 This lead to two significant changes.
707  First, each match list entry now has a single memory descriptor rather
708  than a list of memory descriptors.
709  Second, in addition to exceeding the operation threshold, a memory descriptor
710  can be unlinked when the local offset exceeds a specified value.
711  These changes have lead to several changes in this document: 
712 \layout Enumerate
713
714 Section\SpecialChar ~
715
716 \begin_inset LatexCommand \ref{subsec:paddress}
717
718 \end_inset 
719
720
721 \begin_deeper 
722 \layout Enumerate
723
724 removed references to the memory descriptor list, 
725 \layout Enumerate
726
727 changed the portals address translation description to indicate that unlinking
728  a memory descriptor implies unlinking the associated match list entry--match
729  list entries can no longer be unlinked independently from the memory descriptor.
730  
731 \end_deeper 
732 \layout Enumerate
733
734 Section\SpecialChar ~
735
736 \begin_inset LatexCommand \ref{sec:meattach}
737
738 \end_inset 
739
740
741 \begin_deeper 
742 \layout Enumerate
743
744 removed unlink from argument list, 
745 \layout Enumerate
746
747 removed description of 
748 \family typewriter 
749 ptl_unlink
750 \family default 
751  type, 
752 \layout Enumerate
753
754 changed wording of the error condition when the Portal table index already
755  has an associated match list.
756  
757 \end_deeper 
758 \layout Enumerate
759
760 Section\SpecialChar ~
761
762 \begin_inset LatexCommand \ref{sec:meinsert}
763
764 \end_inset 
765
766 : removed unlink from argument list.
767  
768 \layout Enumerate
769
770 Section\SpecialChar ~
771
772 \begin_inset LatexCommand \ref{sec:md-type}
773
774 \end_inset 
775
776 : added 
777 \family typewriter 
778 max_offset
779 \family default 
780 .
781  
782 \layout Enumerate
783
784 Section\SpecialChar ~
785
786 \begin_inset LatexCommand \ref{sec:mdattach}
787
788 \end_inset 
789
790
791 \begin_deeper 
792 \layout Enumerate
793
794 added description of 
795 \family typewriter 
796 ptl_unlink
797 \family default 
798  type, 
799 \layout Enumerate
800
801 removed reference to memory descriptor lists, 
802 \layout Enumerate
803
804 changed wording of the error condition when match list entry already has
805  an associated memory descriptor, 
806 \layout Enumerate
807
808 changed the description of the 
809 \family typewriter 
810 unlink
811 \family default 
812  argument.
813  
814 \end_deeper 
815 \layout Enumerate
816
817 Section\SpecialChar ~
818
819 \begin_inset LatexCommand \ref{sec:md}
820
821 \end_inset 
822
823 : removed 
824 \family typewriter 
825 PtlMDInsert
826 \family default 
827  operation.
828  
829 \layout Enumerate
830
831 Section\SpecialChar ~
832
833 \begin_inset LatexCommand \ref{sec:mdbind}
834
835 \end_inset 
836
837 : removed references to memory descriptor list.
838  
839 \layout Enumerate
840
841 Section\SpecialChar ~
842
843 \begin_inset LatexCommand \ref{sec:mdfree}
844
845 \end_inset 
846
847 : removed reference to memory descriptor list.
848  
849 \layout Enumerate
850
851 Section\SpecialChar ~
852
853 \begin_inset LatexCommand \ref{sec:summary}
854
855 \end_inset 
856
857 : removed references to PtlMDInsert.
858  
859 \layout Enumerate
860
861 Section\SpecialChar ~
862
863 \begin_inset LatexCommand \ref{sec:semantics}
864
865 \end_inset 
866
867 : removed reference to memory descriptor list.
868  
869 \layout Enumerate
870
871 Section\SpecialChar ~
872
873 \begin_inset LatexCommand \ref{sec:exmpi}
874
875 \end_inset 
876
877 : revised the MPI example to reflect the changes to the interface.
878  
879 \layout Standard
880
881 Several changes have been made to improve the general documentation of the
882  interface.
883  
884 \layout Enumerate
885
886 Section\SpecialChar ~
887
888 \begin_inset LatexCommand \ref{sec:handle-type}
889
890 \end_inset 
891
892 : documented the special value 
893 \family typewriter 
894 PTL_EQ_NONE
895 \family default 
896 .
897  
898 \layout Enumerate
899
900 Section\SpecialChar ~
901
902 \begin_inset LatexCommand \ref{sec:id-type}
903
904 \end_inset 
905
906 : documented the special value 
907 \family typewriter 
908 PTL_ID_ANY
909 \family default 
910 .
911  
912 \layout Enumerate
913
914 Section\SpecialChar ~
915
916 \begin_inset LatexCommand \ref{sec:mdbind}
917
918 \end_inset 
919
920 : documented the return value 
921 \family typewriter 
922 PTL_INV_EQ
923 \layout Enumerate
924
925 Section\SpecialChar ~
926
927 \begin_inset LatexCommand \ref{sec:mdupdate}
928
929 \end_inset 
930
931 : clarified the description of the 
932 \emph on 
933 PtlMDUpdate
934 \emph default 
935  function.
936  
937 \layout Enumerate
938
939 Section\SpecialChar ~
940
941 \begin_inset LatexCommand \ref{sec:implvals}
942
943 \end_inset 
944
945 : introduced a new section to document the implementation defined values.
946  
947 \layout Enumerate
948
949 Section\SpecialChar ~
950
951 \begin_inset LatexCommand \ref{sec:summary}
952
953 \end_inset 
954
955 : modified Table\SpecialChar ~
956
957 \begin_inset LatexCommand \ref{tab:oconsts}
958
959 \end_inset 
960
961  to indicate where each constant is introduced and where it is used.
962  
963 \layout Section*
964
965 Other changes
966 \layout Subsection*
967
968 Implementation defined limits (Section 
969 \begin_inset LatexCommand \ref{sec:niinit}
970
971 \end_inset 
972
973 )
974 \layout Standard
975
976 The earlier version provided implementation defined limits for the maximum
977  number of match entries, the maximum number of memory descriptors, etc.
978  Rather than spanning the entire implementation, these limits are now associated
979  with individual network interfaces.
980 \layout Subsection*
981
982 Added User Ids (Section 
983 \begin_inset LatexCommand \ref{sec:uid}
984
985 \end_inset 
986
987 )
988 \layout Standard
989
990 Group Ids had been used to simplify access control entries.
991  In particular, a process could allow access for all of the processes in
992  a group.
993  User Ids have been introduced to regain this functionality.
994  We use user ids to fill this role.
995 \layout Subsection*
996
997 Removed Group Ids and Rank Ids (Section 
998 \begin_inset LatexCommand \ref{sec:pid}
999
1000 \end_inset 
1001
1002 )
1003 \layout Standard
1004
1005 The earlier version of Portals had two forms for addressing processes: <node
1006  id, process id> and <group id, rank id>.
1007  A process group was defined as the collection processes created during
1008  application launch.
1009  Each process in the group was given a unique rank id in the range 0 to
1010  
1011 \begin_inset Formula $n-1$
1012 \end_inset 
1013
1014  where 
1015 \begin_inset Formula $n$
1016 \end_inset 
1017
1018  was the number of processes in the group.
1019  We removed groups because they are better handled in the runtime system.
1020 \layout Subsection*
1021
1022 Match lists (Section 
1023 \begin_inset LatexCommand \ref{sec:meattach}
1024
1025 \end_inset 
1026
1027 )
1028 \layout Standard
1029
1030 It is no longer illegal to have an existing match entry when calling PtlMEAttach.
1031  A position argument was added to the list of arguments supplied to 
1032 \emph on 
1033 PtlMEAttach
1034 \emph default 
1035  to specify whether the new match entry is prepended or appended to the
1036  existing list.
1037  If there is no existing match list, the position argument is ignored.
1038 \layout Subsection*
1039
1040 Unlinking Memory Descriptors (Section 
1041 \begin_inset LatexCommand \ref{sec:md}
1042
1043 \end_inset 
1044
1045 )
1046 \layout Standard
1047
1048 Previously, a memory descriptor could be unlinked if the offset exceeded
1049  a threshold upon the completion of an operation.
1050  In this version, the unlinking is delayed until there is a matching operation
1051  which requires more memory than is currently available in the descriptor.
1052  In addition to changes in section, this lead to a revision of Figure\SpecialChar ~
1053
1054 \begin_inset LatexCommand \ref{fig:flow}
1055
1056 \end_inset 
1057
1058 .
1059 \layout Subsection*
1060
1061 Split Phase Operations and Events (Section 
1062 \begin_inset LatexCommand \ref{sec:eq}
1063
1064 \end_inset 
1065
1066 )
1067 \layout Standard
1068
1069 Previously, there were five types of events: 
1070 \family typewriter 
1071 PTL_EVENT_PUT
1072 \family default 
1073
1074 \family typewriter 
1075 PTL_EVENT_GET
1076 \family default 
1077
1078 \family typewriter 
1079 PTL_EVENT_REPLY
1080 \family default 
1081
1082 \family typewriter 
1083 PTL_EVENT_SENT
1084 \family default 
1085 , and 
1086 \family typewriter 
1087 PTL_EVENT_ACK.
1088  
1089 \family default 
1090 The first four of these reflected the completion of potentially long operations.
1091  We have introduced new event types to reflect the fact that long operations
1092  have a distinct starting point and a distinct completion point.
1093  Moreover, the completion may be successful or unsuccessful.
1094 \layout Standard
1095
1096 In addition to providing a mechanism for reporting failure to higher levels
1097  of software, this split provides an opportunity for for improved ordering
1098  semantics.
1099  Previously, if one process intiated two operations (e.g., two put operations)
1100  on a remote process, these operations were guaranteed to complete in the
1101  same order that they were initiated.
1102  Now, we only guarantee that the initiation events are delivered in the
1103  same order.
1104  In particular, the operations do not need to complete in the order that
1105  they were intiated.
1106 \layout Subsection*
1107
1108 Well known proces ids (Section 
1109 \begin_inset LatexCommand \ref{sec:niinit}
1110
1111 \end_inset 
1112
1113 )
1114 \layout Standard
1115
1116 To support the notion of 
1117 \begin_inset Quotes eld
1118 \end_inset 
1119
1120 well known process ids,
1121 \begin_inset Quotes erd
1122 \end_inset 
1123
1124  we added a process id argument to the arguments for PtlNIInit.
1125 \layout Chapter*
1126
1127 Glossary
1128 \layout Description
1129
1130 API Application Programming Interface.
1131  A definition of the functions and semantics provided by library of functions.
1132  
1133 \layout Description
1134
1135 Initiator A 
1136 \emph on 
1137 process
1138 \emph default 
1139  that initiates a message operation.
1140  
1141 \layout Description
1142
1143 Message An application-defined unit of data that is exchanged between 
1144 \emph on 
1145 processes
1146 \emph default 
1147 .
1148  
1149 \layout Description
1150
1151 Message\SpecialChar ~
1152 Operation Either a put operation, which writes data, or a get operation,
1153  which reads data.
1154  
1155 \layout Description
1156
1157 Network A network provides point-to-point communication between 
1158 \emph on 
1159 nodes
1160 \emph default 
1161 .
1162  Internally, a network may provide multiple routes between endpoints (to
1163  improve fault tolerance or to improve performance characteristics); however,
1164  multiple paths will not be exposed outside of the network.
1165  
1166 \layout Description
1167
1168 Node A node is an endpoint in a 
1169 \emph on 
1170 network
1171 \emph default 
1172 .
1173  Nodes provide processing capabilities and memory.
1174  A node may provide multiple processors (an SMP node) or it may act as a
1175  
1176 \emph on 
1177 gateway
1178 \emph default 
1179  between networks.
1180  
1181 \layout Description
1182
1183 Process A context of execution.
1184  A process defines a virtual memory (VM) context.
1185  This context is not shared with other processes.
1186  Several threads may share the VM context defined by a process.
1187  
1188 \layout Description
1189
1190 Target A 
1191 \emph on 
1192 process
1193 \emph default 
1194  that is acted upon by a message operation.
1195  
1196 \layout Description
1197
1198 Thread A context of execution that shares a VM context with other threads.
1199  
1200 \layout Standard
1201
1202
1203 \begin_inset ERT
1204 status Collapsed
1205
1206 \layout Standard
1207
1208 \backslash 
1209 cleardoublepage
1210 \layout Standard
1211
1212 \backslash 
1213 setcounter{page}{1}
1214 \backslash 
1215 pagenumbering{arabic}
1216 \end_inset 
1217
1218
1219 \layout Chapter
1220
1221 Introduction
1222 \begin_inset LatexCommand \label{sec:intro}
1223
1224 \end_inset 
1225
1226
1227 \layout Section
1228
1229 Overview
1230 \layout Standard
1231
1232 This document describes an application programming interface for message
1233  passing between nodes in a system area network.
1234  The goal of this interface is to improve the scalability and performance
1235  of network communication by defining the functions and semantics of message
1236  passing required for scaling a parallel computing system to ten thousand
1237  nodes.
1238  This goal is achieved by providing an interface that will allow a quality
1239  implementation to take advantage of the inherently scalable design of Portals.
1240 \layout Standard
1241
1242 This document is divided into several sections: 
1243 \layout Description
1244
1245 Section\SpecialChar ~
1246
1247 \begin_inset LatexCommand \ref{sec:intro}
1248
1249 \end_inset 
1250
1251 ---Introduction This section describes the purpose and scope of the Portals
1252  API.
1253  
1254 \layout Description
1255
1256 Section\SpecialChar ~
1257
1258 \begin_inset LatexCommand \ref{sec:apiover}
1259
1260 \end_inset 
1261
1262 ---An\SpecialChar ~
1263 Overview\SpecialChar ~
1264 of\SpecialChar ~
1265 the\SpecialChar ~
1266 Portals\SpecialChar ~
1267 3.1\SpecialChar ~
1268 API This section gives a brief overview of the
1269  Portals API.
1270  The goal is to introduce the key concepts and terminology used in the descripti
1271 on of the API.
1272  
1273 \layout Description
1274
1275 Section\SpecialChar ~
1276
1277 \begin_inset LatexCommand \ref{sec:api}
1278
1279 \end_inset 
1280
1281 ---The\SpecialChar ~
1282 Portals\SpecialChar ~
1283 3.2\SpecialChar ~
1284 API This section describes the functions and semantics of
1285  the Portals application programming interface.
1286  
1287 \layout Description
1288
1289 Section\SpecialChar ~
1290
1291 \begin_inset LatexCommand \ref{sec:semantics}
1292
1293 \end_inset 
1294
1295 --The\SpecialChar ~
1296 Semantics\SpecialChar ~
1297 of\SpecialChar ~
1298 Message\SpecialChar ~
1299 Transmission This section describes the semantics
1300  of message transmission.
1301  In particular, the information transmitted in each type of message and
1302  the processing of incoming messages.
1303  
1304 \layout Description
1305
1306 Section\SpecialChar ~
1307
1308 \begin_inset LatexCommand \ref{sec:examples}
1309
1310 \end_inset 
1311
1312 ---Examples This section presents several examples intended to illustrates
1313  the use of the Portals API.
1314  
1315 \layout Section
1316
1317 Purpose
1318 \layout Standard
1319
1320 Existing message passing technologies available for commodity cluster networking
1321  hardware do not meet the scalability goals required by the Cplant\SpecialChar ~
1322
1323 \begin_inset LatexCommand \cite{Cplant}
1324
1325 \end_inset 
1326
1327  project at Sandia National Laboratories.
1328  The goal of the Cplant project is to construct a commodity cluster that
1329  can scale to the order of ten thousand nodes.
1330  This number greatly exceeds the capacity for which existing message passing
1331  technologies have been designed and implemented.
1332 \layout Standard
1333
1334 In addition to the scalability requirements of the network, these technologies
1335  must also be able to support a scalable implementation of the Message Passing
1336  Interface (MPI)\SpecialChar ~
1337
1338 \begin_inset LatexCommand \cite{MPIstandard}
1339
1340 \end_inset 
1341
1342  standard, which has become the 
1343 \shape italic 
1344 de facto
1345 \shape default 
1346  standard for parallel scientific computing.
1347  While MPI does not impose any scalability limitations, existing message
1348  passing technologies do not provide the functionality needed to allow implement
1349 ations of MPI to meet the scalability requirements of Cplant.
1350 \layout Standard
1351
1352 The following are properties of a network architecture that do not impose
1353  any inherent scalability limitations: 
1354 \layout Itemize
1355
1356 Connectionless - Many connection-oriented architectures, such as VIA\SpecialChar ~
1357
1358 \begin_inset LatexCommand \cite{VIA}
1359
1360 \end_inset 
1361
1362  and TCP/IP sockets, have limitations on the number of peer connections
1363  that can be established.
1364  
1365 \layout Itemize
1366
1367 Network independence - Many communication systems depend on the host processor
1368  to perform operations in order for messages in the network to be consumed.
1369  Message consumption from the network should not be dependent on host processor
1370  activity, such as the operating system scheduler or user-level thread scheduler.
1371  
1372 \layout Itemize
1373
1374 User-level flow control - Many communication systems manage flow control
1375  internally to avoid depleting resources, which can significantly impact
1376  performance as the number of communicating processes increases.
1377  
1378 \layout Itemize
1379
1380 OS Bypass - High performance network communication should not involve memory
1381  copies into or out of a kernel-managed protocol stack.
1382  
1383 \layout Standard
1384
1385 The following are properties of a network architecture that do not impose
1386  scalability limitations for an implementation of MPI:
1387 \layout Itemize
1388
1389 Receiver-managed - Sender-managed message passing implementations require
1390  a persistent block of memory to be available for every process, requiring
1391  memory resources to increase with job size and requiring user-level flow
1392  control mechanisms to manage these resources.
1393  
1394 \layout Itemize
1395
1396 User-level Bypass - While OS Bypass is necessary for high-performance, it
1397  alone is not sufficient to support the Progress Rule of MPI asynchronous
1398  operations.
1399  
1400 \layout Itemize
1401
1402 Unexpected messages - Few communication systems have support for receiving
1403  messages for which there is no prior notification.
1404  Support for these types of messages is necessary to avoid flow control
1405  and protocol overhead.
1406  
1407 \layout Section
1408
1409 Background
1410 \layout Standard
1411
1412 Portals was originally designed for and implemented on the nCube machine
1413  as part of the SUNMOS (Sandia/UNM OS)\SpecialChar ~
1414
1415 \begin_inset LatexCommand \cite{SUNMOS}
1416
1417 \end_inset 
1418
1419  and Puma\SpecialChar ~
1420
1421 \begin_inset LatexCommand \cite{PumaOS}
1422
1423 \end_inset 
1424
1425  lightweight kernel development projects.
1426  Portals went through two design phases, the latter of which is used on
1427  the 4500-node Intel TeraFLOPS machine\SpecialChar ~
1428
1429 \begin_inset LatexCommand \cite{TFLOPS}
1430
1431 \end_inset 
1432
1433 .
1434  Portals have been very successful in meeting the needs of such a large
1435  machine, not only as a layer for a high-performance MPI implementation\SpecialChar ~
1436
1437 \begin_inset LatexCommand \cite{PumaMPI}
1438
1439 \end_inset 
1440
1441 , but also for implementing the scalable run-time environment and parallel
1442  I/O capabilities of the machine.
1443 \layout Standard
1444
1445 The second generation Portals implementation was designed to take full advantage
1446  of the hardware architecture of large MPP machines.
1447  However, efforts to implement this same design on commodity cluster technology
1448  identified several limitations, due to the differences in network hardware
1449  as well as to shortcomings in the design of Portals.
1450 \layout Section
1451
1452 Scalability
1453 \layout Standard
1454
1455 The primary goal in the design of Portals is scalability.
1456  Portals are designed specifically for an implementation capable of supporting
1457  a parallel job running on tens of thousands of nodes.
1458  Performance is critical only in terms of scalability.
1459  That is, the level of message passing performance is characterized by how
1460  far it allows an application to scale and not by how it performs in micro-bench
1461 marks (e.g., a two node bandwidth or latency test).
1462 \layout Standard
1463
1464 The Portals API is designed to allow for scalability, not to guarantee it.
1465  Portals cannot overcome the shortcomings of a poorly designed application
1466  program.
1467  Applications that have inherent scalability limitations, either through
1468  design or implementation, will not be transformed by Portals into scalable
1469  applications.
1470  Scalability must be addressed at all levels.
1471  Portals do not inhibit scalability, but do not guarantee it either.
1472 \layout Standard
1473
1474 To support scalability, the Portals interface maintains a minimal amount
1475  of state.
1476  Portals provide reliable, ordered delivery of messages between pairs of
1477  processes.
1478  They are connectionless: a process is not required to explicitly establish
1479  a point-to-point connection with another process in order to communicate.
1480  Moreover, all buffers used in the transmission of messages are maintained
1481  in user space.
1482  The target process determines how to respond to incoming messages, and
1483  messages for which there are no buffers are discarded.
1484 \layout Section
1485
1486 Communication Model
1487 \layout Standard
1488
1489 Portals combine the characteristics of both one-side and two-sided communication.
1490  They define a 
1491 \begin_inset Quotes eld
1492 \end_inset 
1493
1494 matching put
1495 \begin_inset Quotes erd
1496 \end_inset 
1497
1498  operation and a 
1499 \begin_inset Quotes eld
1500 \end_inset 
1501
1502 matching get
1503 \begin_inset Quotes erd
1504 \end_inset 
1505
1506  operation.
1507  The destination of a put (or send) is not an explicit address; instead,
1508  each message contains a set of match bits that allow the receiver to determine
1509  where incoming messages should be placed.
1510  This flexibility allows Portals to support both traditional one-sided operation
1511 s and two-sided send/receive operations.
1512 \layout Standard
1513
1514 Portals allows the target to determine whether incoming messages are acceptable.
1515  A target process can choose to accept message operations from any specific
1516  process or can choose to ignore message operations from any specific process.
1517 \layout Section
1518
1519 Zero Copy, OS Bypass and Application Bypass
1520 \layout Standard
1521
1522 In traditional system architectures, network packets arrive at the network
1523  interface card (NIC), are passed through one or more protocol layers in
1524  the operating system, and eventually copied into the address space of the
1525  application.
1526  As network bandwidth began to approach memory copy rates, reduction of
1527  memory copies became a critical concern.
1528  This concern lead to the development of zero-copy message passing protocols
1529  in which message copies are eliminated or pipelined to avoid the loss of
1530  bandwidth.
1531 \layout Standard
1532
1533 A typical zero-copy protocol has the NIC generate an interrupt for the CPU
1534  when a message arrives from the network.
1535  The interrupt handler then controls the transfer of the incoming message
1536  into the address space of the appropriate application.
1537  The interrupt latency, the time from the initiation of an interrupt until
1538  the interrupt handler is running, is fairly significant.
1539  To avoid this cost, some modern NICs have processors that can be programmed
1540  to implement part of a message passing protocol.
1541  Given a properly designed protocol, it is possible to program the NIC to
1542  control the transfer of incoming messages, without needing to interrupt
1543  the CPU.
1544  Because this strategy does not need to involve the OS on every message
1545  transfer, it is frequently called 
1546 \begin_inset Quotes eld
1547 \end_inset 
1548
1549 OS Bypass.
1550 \begin_inset Quotes erd
1551 \end_inset 
1552
1553  ST\SpecialChar ~
1554
1555 \begin_inset LatexCommand \cite{ST}
1556
1557 \end_inset 
1558
1559 , VIA\SpecialChar ~
1560
1561 \begin_inset LatexCommand \cite{VIA}
1562
1563 \end_inset 
1564
1565 , FM\SpecialChar ~
1566
1567 \begin_inset LatexCommand \cite{FM2}
1568
1569 \end_inset 
1570
1571 , GM\SpecialChar ~
1572
1573 \begin_inset LatexCommand \cite{GM}
1574
1575 \end_inset 
1576
1577 , and Portals are examples of OS Bypass protocols.
1578 \layout Standard
1579
1580 Many protocols that support OS Bypass still require that the application
1581  actively participate in the protocol to ensure progress.
1582  As an example, the long message protocol of PM requires that the application
1583  receive and reply to a request to put or get a long message.
1584  This complicates the runtime environment, requiring a thread to process
1585  incoming requests, and significantly increases the latency required to
1586  initiate a long message protocol.
1587  The Portals message passing protocol does not require activity on the part
1588  of the application to ensure progress.
1589  We use the term 
1590 \begin_inset Quotes eld
1591 \end_inset 
1592
1593 Application Bypass
1594 \begin_inset Quotes erd
1595 \end_inset 
1596
1597  to refer to this aspect of the Portals protocol.
1598 \layout Section
1599
1600 Faults 
1601 \layout Standard
1602
1603 Given the number of components that we are dealing with and the fact that
1604  we are interested in supporting applications that run for very long times,
1605  failures are inevitable.
1606  The Portals API recognizes that the underlying transport may not be able
1607  to successfully complete an operation once it has been initiated.
1608  This is reflected in the fact that the Portals API reports three types
1609  of events: events indicating the initiation of an operation, events indicating
1610  the successful completion of an operation, and events indicating the unsuccessf
1611 ul completion of an operation.
1612  Every initiation event is eventually followed by a successful completion
1613  event or an unsuccessful completion event.
1614 \layout Standard
1615
1616 Between the time an operation is started and the time that the operation
1617  completes (successfully or unsuccessfully), any memory associated with
1618  the operation should be considered volatile.
1619  That is, the memory may be changed in unpredictable ways while the operation
1620  is progressing.
1621  Once the operation completes, the memory associated with the operation
1622  will not be subject to further modification (from this operation).
1623  Notice that unsuccessful operations may alter memory in an essentially
1624  unpredictable fashion.
1625 \layout Chapter
1626
1627 An Overview of the Portals API
1628 \begin_inset LatexCommand \label{sec:apiover}
1629
1630 \end_inset 
1631
1632
1633 \layout Standard
1634
1635 In this section, we give a conceptual overview of the Portals API.
1636  The goal is to provide a context for understanding the detailed description
1637  of the API presented in the next section.
1638 \layout Section
1639
1640 Data Movement
1641 \begin_inset LatexCommand \label{sec:dmsemantics}
1642
1643 \end_inset 
1644
1645
1646 \layout Standard
1647
1648 A Portal represents an opening in the address space of a process.
1649  Other processes can use a Portal to read (get) or write (put) the memory
1650  associated with the portal.
1651  Every data movement operation involves two processes, the 
1652 \series bold 
1653 initiator
1654 \series default 
1655  and the 
1656 \series bold 
1657 target
1658 \series default 
1659 .
1660  The initiator is the process that initiates the data movement operation.
1661  The target is the process that responds to the operation by either accepting
1662  the data for a put operation, or replying with the data for a get operation.
1663 \layout Standard
1664
1665 In this discussion, activities attributed to a process may refer to activities
1666  that are actually performed by the process or 
1667 \emph on 
1668 on behalf of the process
1669 \emph default 
1670 .
1671  The inclusiveness of our terminology is important in the context of 
1672 \emph on 
1673 application bypass
1674 \emph default 
1675 .
1676  In particular, when we note that the target sends a reply in the case of
1677  a get operation, it is possible that reply will be generated by another
1678  component in the system, bypassing the application.
1679 \layout Standard
1680
1681 Figures\SpecialChar ~
1682
1683 \begin_inset LatexCommand \ref{fig:put}
1684
1685 \end_inset 
1686
1687  and 
1688 \begin_inset LatexCommand \ref{fig:get}
1689
1690 \end_inset 
1691
1692  present graphical interpretations of the Portal data movement operations:
1693  put and get.
1694  In the case of a put operation, the initiator sends a put request message
1695  containing the data to the target.
1696  The target translates the Portal addressing information in the request
1697  using its local Portal structures.
1698  When the request has been processed, the target optionally sends an acknowledge
1699 ment message.
1700 \layout Standard
1701
1702
1703 \begin_inset Float figure
1704 placement htbp
1705 wide false
1706 collapsed false
1707
1708 \layout Standard
1709 \align center 
1710
1711 \begin_inset Graphics FormatVersion 1
1712         filename put.eps
1713         display color
1714         size_type 0
1715         rotateOrigin center
1716         lyxsize_type 1
1717         lyxwidth 218pt
1718         lyxheight 119pt
1719 \end_inset 
1720
1721
1722 \layout Caption
1723
1724 Portal Put (Send)
1725 \begin_inset LatexCommand \label{fig:put}
1726
1727 \end_inset 
1728
1729
1730 \end_inset 
1731
1732
1733 \layout Standard
1734
1735 In the case of a get operation, the initiator sends a get request to the
1736  target.
1737  As with the put operation, the target translates the Portal addressing
1738  information in the request using its local Portal structures.
1739  Once it has translated the Portal addressing information, the target sends
1740  a reply that includes the requested data.
1741 \layout Standard
1742
1743
1744 \begin_inset Float figure
1745 placement htbp
1746 wide false
1747 collapsed false
1748
1749 \layout Standard
1750 \align center 
1751
1752 \begin_inset Graphics FormatVersion 1
1753         filename get.eps
1754         display color
1755         size_type 0
1756         rotateOrigin center
1757         lyxsize_type 1
1758         lyxwidth 218pt
1759         lyxheight 119pt
1760 \end_inset 
1761
1762
1763 \layout Caption
1764
1765 Portal Get
1766 \begin_inset LatexCommand \label{fig:get}
1767
1768 \end_inset 
1769
1770
1771 \end_inset 
1772
1773
1774 \layout Standard
1775
1776 We should note that Portal address translations are only performed on nodes
1777  that respond to operations initiated by other nodes.
1778  Acknowledgements and replies to get operations bypass the portals address
1779  translation structures.
1780 \layout Section
1781
1782 Portal Addressing
1783 \begin_inset LatexCommand \label{subsec:paddress}
1784
1785 \end_inset 
1786
1787
1788 \layout Standard
1789
1790 One-sided data movement models (e.g., shmem\SpecialChar ~
1791
1792 \begin_inset LatexCommand \cite{CraySHMEM}
1793
1794 \end_inset 
1795
1796 , ST\SpecialChar ~
1797
1798 \begin_inset LatexCommand \cite{ST}
1799
1800 \end_inset 
1801
1802 , MPI-2\SpecialChar ~
1803
1804 \begin_inset LatexCommand \cite{MPI2}
1805
1806 \end_inset 
1807
1808 ) typically use a triple to address memory on a remote node.
1809  This triple consists of a process id, memory buffer id, and offset.
1810  The process id identifies the target process, the memory buffer id specifies
1811  the region of memory to be used for the operation, and the offset specifies
1812  an offset within the memory buffer.
1813 \layout Standard
1814
1815 In addition to the standard address components (process id, memory buffer
1816  id, and offset), a Portal address includes a set of match bits.
1817  This addressing model is appropriate for supporting one-sided operations
1818  as well as traditional two-sided message passing operations.
1819  Specifically, the Portals API provides the flexibility needed for an efficient
1820  implementation of MPI-1, which defines two-sided operations with one-sided
1821  completion semantics.
1822 \layout Standard
1823
1824 Figure\SpecialChar ~
1825
1826 \begin_inset LatexCommand \ref{fig:portals}
1827
1828 \end_inset 
1829
1830  presents a graphical representation of the structures used by a target
1831  in the interpretation of a Portal address.
1832  The process id is used to route the message to the appropriate node and
1833  is not reflected in this diagram.
1834  The memory buffer id, called the 
1835 \series bold 
1836 portal id
1837 \series default 
1838 , is used as an index into the Portal table.
1839  Each element of the Portal table identifies a match list.
1840  Each element of the match list specifies two bit patterns: a set of 
1841 \begin_inset Quotes eld
1842 \end_inset 
1843
1844 don't care
1845 \begin_inset Quotes erd
1846 \end_inset 
1847
1848  bits, and a set of 
1849 \begin_inset Quotes eld
1850 \end_inset 
1851
1852 must match
1853 \begin_inset Quotes erd
1854 \end_inset 
1855
1856  bits.
1857  In addition to the two sets of match bits, each match list element has
1858  at most one memory descriptor.
1859  Each memory descriptor identifies a memory region and an optional event
1860  queue.
1861  The memory region specifies the memory to be used in the operation and
1862  the event queue is used to record information about these operations.
1863 \layout Standard
1864
1865
1866 \begin_inset Float figure
1867 placement htbp
1868 wide false
1869 collapsed false
1870
1871 \layout Standard
1872 \align center 
1873
1874 \begin_inset Graphics FormatVersion 1
1875         filename portals.eps
1876         display color
1877         size_type 0
1878         rotateOrigin center
1879         lyxsize_type 1
1880         lyxwidth 305pt
1881         lyxheight 106pt
1882 \end_inset 
1883
1884
1885 \layout Caption
1886
1887 Portal Addressing Structures
1888 \begin_inset LatexCommand \label{fig:portals}
1889
1890 \end_inset 
1891
1892
1893 \end_inset 
1894
1895
1896 \layout Standard
1897
1898 Figure\SpecialChar ~
1899
1900 \begin_inset LatexCommand \ref{fig:flow}
1901
1902 \end_inset 
1903
1904  illustrates the steps involved in translating a Portal address, starting
1905  from the first element in a match list.
1906  If the match criteria specified in the match list entry are met and the
1907  memory descriptor list accepts the operation
1908 \begin_inset Foot
1909 collapsed true
1910
1911 \layout Standard
1912
1913 Memory descriptors can reject operations because a threshold has been exceeded
1914  or because the memory region does not have sufficient space, see Section\SpecialChar ~
1915
1916 \begin_inset LatexCommand \ref{sec:md}
1917
1918 \end_inset 
1919
1920
1921 \end_inset 
1922
1923 , the operation (put or get) is performed using the memory region specified
1924  in the memory descriptor.
1925  If the memory descriptor specifies that it is to be unlinked when a threshold
1926  has been exceeded, the match list entry is removed from the match list
1927  and the resources associated with the memory descriptor and match list
1928  entry are reclaimed.
1929  Finally, if there is an event queue specified in the memory descriptor,
1930  the operation is logged in the event queue.
1931 \layout Standard
1932
1933
1934 \begin_inset Float figure
1935 placement htbp
1936 wide false
1937 collapsed false
1938
1939 \layout Standard
1940 \align center 
1941
1942 \begin_inset Graphics FormatVersion 1
1943         filename flow_new.eps
1944         display color
1945         size_type 0
1946         rotateOrigin center
1947         lyxsize_type 1
1948         lyxwidth 447pt
1949         lyxheight 282pt
1950 \end_inset 
1951
1952
1953 \layout Caption
1954
1955 Portals Address Translation
1956 \begin_inset LatexCommand \label{fig:flow}
1957
1958 \end_inset 
1959
1960
1961 \end_inset 
1962
1963
1964 \layout Standard
1965
1966 If the match criteria specified in the match list entry are not met, or
1967  there is no memory descriptor associated with the match list entry, or
1968  the memory descriptor associated with the match list entry rejects the
1969  operation, the address translation continues with the next match list entry.
1970  If the end of the match list has been reached, the address translation
1971  is aborted and the incoming requested is discarded.
1972 \layout Section
1973
1974 Access Control
1975 \layout Standard
1976
1977 A process can control access to its portals using an access control list.
1978  Each entry in the access control list specifies a process id and a Portal
1979  table index.
1980  The access control list is actually an array of entries.
1981  Each incoming request includes an index into the access control list (i.e.,
1982  a 
1983 \begin_inset Quotes eld
1984 \end_inset 
1985
1986 cookie
1987 \begin_inset Quotes erd
1988 \end_inset 
1989
1990  or hint).
1991  If the id of the process issuing the request doesn't match the id specified
1992  in the access control list entry or the Portal table index specified in
1993  the request doesn't match the Portal table index specified in the access
1994  control list entry, the request is rejected.
1995  Process identifiers and Portal table indexes may include wild card values
1996  to increase the flexibility of this mechanism.
1997  
1998 \layout Standard
1999
2000 Two aspects of this design merit further discussion.
2001  First, the model assumes that the information in a message header, the
2002  sender's id in particular, is trustworthy.
2003  In most contexts, we assume that the entity that constructs the header
2004  is trustworthy; however, using cryptographic techniques, we could easily
2005  devise a protocol that would ensure the authenticity of the sender.
2006 \layout Standard
2007
2008 Second, because the access check is performed by the receiver, it is possible
2009  that a malicious process will generate thousands of messages that will
2010  be denied by the receiver.
2011  This could saturate the network and/or the receiver, resulting in a 
2012 \emph on 
2013 denial of service
2014 \emph default 
2015  attack.
2016  Moving the check to the sender using capabilities, would remove the potential
2017  for this form of attack.
2018  However, the solution introduces the complexities of capability management
2019  (exchange of capabilities, revocation, protections, etc).
2020 \layout Section
2021
2022 Multi-threaded Applications
2023 \begin_inset LatexCommand \label{sec:threads}
2024
2025 \end_inset 
2026
2027  
2028 \layout Standard
2029
2030 The Portals API supports a generic view of multi-threaded applications.
2031  From the perspective of the Portals API, an application program is defined
2032  by a set of processes.
2033  Each process defines a unique address space.
2034  The Portals API defines access to this address space from other processes
2035  (using portals addressing and the data movement operations).
2036  A process may have one or more 
2037 \emph on 
2038 threads
2039 \emph default 
2040  executing in its address space.
2041  
2042 \layout Standard
2043
2044 With the exception of 
2045 \emph on 
2046 PtlEQWait
2047 \emph default 
2048  every function in the Portals API is non-blocking and atomic with respect
2049  to both other threads and external operations that result from data movement
2050  operations.
2051  While individual operations are atomic, sequences of these operations may
2052  be interleaved between different threads and with external operations.
2053  The Portals API does not provide any mechanisms to control this interleaving.
2054  It is expected that these mechanisms will be provided by the API used to
2055  create threads.
2056 \layout Chapter
2057
2058 The Portals API
2059 \begin_inset LatexCommand \label{sec:api}
2060
2061 \end_inset 
2062
2063
2064 \layout Section
2065
2066 Naming Conventions
2067 \begin_inset LatexCommand \label{sec:conv}
2068
2069 \end_inset 
2070
2071
2072 \layout Standard
2073
2074 The Portals API defines two types of entities: functions and types.
2075  Function always start with 
2076 \emph on 
2077 Ptl
2078 \emph default 
2079  and use mixed upper and lower case.
2080  When used in the body of this report, function names appear in italic face,
2081  e.g., 
2082 \emph on 
2083 PtlInit
2084 \emph default 
2085 .
2086  The functions associated with an object type will have names that start
2087  with 
2088 \emph on 
2089 Ptl
2090 \emph default 
2091 , followed by the two letter object type code shown in Table\SpecialChar ~
2092
2093 \begin_inset LatexCommand \ref{tab:objcodes}
2094
2095 \end_inset 
2096
2097 .
2098  As an example, the function 
2099 \emph on 
2100 PtlEQAlloc
2101 \emph default 
2102  allocates resources for an event queue.
2103 \layout Standard
2104
2105
2106 \begin_inset Float table
2107 placement htbp
2108 wide false
2109 collapsed false
2110
2111 \layout Caption
2112
2113 Object Type Codes
2114 \begin_inset LatexCommand \label{tab:objcodes}
2115
2116 \end_inset 
2117
2118
2119 \begin_inset ERT
2120 status Collapsed
2121
2122 \layout Standard
2123  
2124 \backslash 
2125 medskip
2126 \newline 
2127   
2128 \end_inset 
2129
2130
2131 \layout Standard
2132 \align center 
2133
2134 \size small 
2135
2136 \begin_inset  Tabular
2137 <lyxtabular version="3" rows="5" columns="3">
2138 <features firstHeadEmpty="true">
2139 <column alignment="left" valignment="top" width="0pt">
2140 <column alignment="left" valignment="top" width="0pt">
2141 <column alignment="left" valignment="top" width="0pt">
2142 <row bottomline="true">
2143 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2144 \begin_inset Text
2145
2146 \layout Standard
2147
2148  
2149 \emph on 
2150 xx
2151 \end_inset 
2152 </cell>
2153 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158  Name 
2159 \end_inset 
2160 </cell>
2161 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166  Section 
2167 \end_inset 
2168 </cell>
2169 </row>
2170 <row>
2171 <cell alignment="left" valignment="top" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 EQ 
2177 \end_inset 
2178 </cell>
2179 <cell alignment="left" valignment="top" usebox="none">
2180 \begin_inset Text
2181
2182 \layout Standard
2183
2184  Event Queue 
2185 \end_inset 
2186 </cell>
2187 <cell alignment="left" valignment="top" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192  
2193 \begin_inset LatexCommand \ref{sec:eq}
2194
2195 \end_inset 
2196
2197
2198 \end_inset 
2199 </cell>
2200 </row>
2201 <row>
2202 <cell alignment="left" valignment="top" usebox="none">
2203 \begin_inset Text
2204
2205 \layout Standard
2206
2207  MD 
2208 \end_inset 
2209 </cell>
2210 <cell alignment="left" valignment="top" usebox="none">
2211 \begin_inset Text
2212
2213 \layout Standard
2214
2215  Memory Descriptor 
2216 \end_inset 
2217 </cell>
2218 <cell alignment="left" valignment="top" usebox="none">
2219 \begin_inset Text
2220
2221 \layout Standard
2222
2223  
2224 \begin_inset LatexCommand \ref{sec:md}
2225
2226 \end_inset 
2227
2228
2229 \end_inset 
2230 </cell>
2231 </row>
2232 <row>
2233 <cell alignment="left" valignment="top" usebox="none">
2234 \begin_inset Text
2235
2236 \layout Standard
2237
2238  ME 
2239 \end_inset 
2240 </cell>
2241 <cell alignment="left" valignment="top" usebox="none">
2242 \begin_inset Text
2243
2244 \layout Standard
2245
2246  Match list Entry 
2247 \end_inset 
2248 </cell>
2249 <cell alignment="left" valignment="top" usebox="none">
2250 \begin_inset Text
2251
2252 \layout Standard
2253
2254  
2255 \begin_inset LatexCommand \ref{sec:me}
2256
2257 \end_inset 
2258
2259
2260 \end_inset 
2261 </cell>
2262 </row>
2263 <row>
2264 <cell alignment="left" valignment="top" usebox="none">
2265 \begin_inset Text
2266
2267 \layout Standard
2268
2269  NI 
2270 \end_inset 
2271 </cell>
2272 <cell alignment="left" valignment="top" usebox="none">
2273 \begin_inset Text
2274
2275 \layout Standard
2276
2277  Network Interface 
2278 \end_inset 
2279 </cell>
2280 <cell alignment="left" valignment="top" usebox="none">
2281 \begin_inset Text
2282
2283 \layout Standard
2284
2285  
2286 \begin_inset LatexCommand \ref{sec:ni}
2287
2288 \end_inset 
2289
2290
2291 \end_inset 
2292 </cell>
2293 </row>
2294 </lyxtabular>
2295
2296 \end_inset 
2297
2298
2299 \end_inset 
2300
2301
2302 \layout Standard
2303
2304 Type names use lower case with underscores to separate words.
2305  Each type name starts with 
2306 \family typewriter 
2307 ptl
2308 \family default 
2309 _ and ends with 
2310 \family typewriter 
2311 _t
2312 \family default 
2313 .
2314  When used in the body of this report, type names appear in a fixed font,
2315  e.g., 
2316 \family typewriter 
2317 ptl_match_bits_t
2318 \family default 
2319 .
2320 \layout Standard
2321
2322 Names for constants use upper case with underscores to separate words.
2323  Each constant name starts with 
2324 \family typewriter 
2325 PTL_
2326 \family default 
2327 .
2328  When used in the body of this report, type names appear in a fixed font,
2329  e.g., 
2330 \family typewriter 
2331 PTL_OK
2332 \family default 
2333 .
2334 \layout Section
2335
2336 Base Types
2337 \layout Standard
2338
2339 The Portals API defines a variety of base types.
2340  These types represent a simple renaming of the base types provided by the
2341  C programming language.
2342  In most cases these new type names have been introduced to improve type
2343  safety and to avoid issues arising from differences in representation sizes
2344  (e.g., 16-bit or 32-bit integers).
2345 \layout Subsection
2346
2347 Sizes
2348 \begin_inset LatexCommand \label{sec:size-t}
2349
2350 \end_inset 
2351
2352  
2353 \layout Standard
2354
2355 The type 
2356 \family typewriter 
2357 ptl_size_t
2358 \family default 
2359  is an unsigned 64-bit integral type used for representing sizes.
2360 \layout Subsection
2361
2362 Handles
2363 \begin_inset LatexCommand \label{sec:handle-type}
2364
2365 \end_inset 
2366
2367  
2368 \layout Standard
2369
2370 Objects maintained by the API are accessed through handles.
2371  Handle types have names of the form 
2372 \family typewriter 
2373 ptl_handle_
2374 \emph on 
2375 xx
2376 \emph default 
2377 _t
2378 \family default 
2379 , where 
2380 \emph on 
2381 xx
2382 \emph default 
2383  is one of the two letter object type codes shown in Table\SpecialChar ~
2384
2385 \begin_inset LatexCommand \ref{tab:objcodes}
2386
2387 \end_inset 
2388
2389 .
2390  For example, the type 
2391 \family typewriter 
2392 ptl_handle_ni_t
2393 \family default 
2394  is used for network interface handles.
2395 \layout Standard
2396
2397 Each type of object is given a unique handle type to enhance type checking.
2398  The type, 
2399 \family typewriter 
2400 ptl_handle_any_t
2401 \family default 
2402 , can be used when a generic handle is needed.
2403  Every handle value can be converted into a value of type 
2404 \family typewriter 
2405 ptl_handle_any_t
2406 \family default 
2407  without loss of information.
2408 \layout Standard
2409
2410 Handles are not simple values.
2411  Every portals object is associated with a specific network interface and
2412  an identifier for this interface (along with an object identifier) is part
2413  of the handle for the object.
2414 \layout Standard
2415
2416 The special value 
2417 \family typewriter 
2418 PTL_EQ_NONE
2419 \family default 
2420 , of type 
2421 \family typewriter 
2422 ptl_handle_eq_t
2423 \family default 
2424 , is used to indicate the absence of an event queue.
2425  See sections 
2426 \begin_inset LatexCommand \ref{sec:mdfree}
2427
2428 \end_inset 
2429
2430  and\SpecialChar ~
2431
2432 \begin_inset LatexCommand \ref{sec:mdupdate}
2433
2434 \end_inset 
2435
2436  for uses of this value.
2437 \layout Subsection
2438
2439 Indexes
2440 \begin_inset LatexCommand \label{sec:index-type}
2441
2442 \end_inset 
2443
2444  
2445 \layout Standard
2446
2447 The types 
2448 \family typewriter 
2449 ptl_pt_index_t
2450 \family default 
2451  and 
2452 \family typewriter 
2453 ptl_ac_index_t
2454 \family default 
2455  are integral types used for representing Portal table indexes and access
2456  control tables indexes, respectively.
2457  See section\SpecialChar ~
2458
2459 \begin_inset LatexCommand \ref{sec:niinit}
2460
2461 \end_inset 
2462
2463  for limits on values of these types.
2464 \layout Subsection
2465
2466 Match Bits
2467 \begin_inset LatexCommand \label{sec:mb-type}
2468
2469 \end_inset 
2470
2471  
2472 \layout Standard
2473
2474 The type 
2475 \family typewriter 
2476 ptl_match_bits_t
2477 \family default 
2478  is capable of holding unsigned 64-bit integer values.
2479 \layout Subsection
2480
2481 Network Interfaces
2482 \begin_inset LatexCommand \label{sec:ni-type}
2483
2484 \end_inset 
2485
2486  
2487 \layout Standard
2488
2489 The type 
2490 \family typewriter 
2491 ptl_interface_t
2492 \family default 
2493  is an integral type used for identifying different network interfaces.
2494  Users will need to consult the local documentation to determine appropriate
2495  values for the interfaces available.
2496  The special value 
2497 \family typewriter 
2498 PTL_IFACE_DEFAULT
2499 \family default 
2500  identifies the default interface.
2501 \layout Subsection
2502
2503 Identifiers
2504 \begin_inset LatexCommand \label{sec:id-type}
2505
2506 \end_inset 
2507
2508
2509 \layout Standard
2510
2511 The type 
2512 \family typewriter 
2513 ptl_nid_t
2514 \family default 
2515  is an integral type used for representing node ids
2516 \family typewriter 
2517 , ptl_pid_t
2518 \family default 
2519  is an integral type for representing process ids, and 
2520 \family typewriter 
2521 ptl_uid_t 
2522 \family default 
2523 is an integral type for representing user ids.
2524 \layout Standard
2525
2526 The special values 
2527 \family typewriter 
2528 PTL_PID_ANY
2529 \family default 
2530  matches any process identifier, PTL_NID_ANY matches any node identifier,
2531  and 
2532 \family typewriter 
2533 PTL_UID_ANY
2534 \family default 
2535  matches any user identifier.
2536  See sections 
2537 \begin_inset LatexCommand \ref{sec:meattach}
2538
2539 \end_inset 
2540
2541  and\SpecialChar ~
2542
2543 \begin_inset LatexCommand \ref{sec:acentry}
2544
2545 \end_inset 
2546
2547  for uses of these values.
2548 \layout Subsection
2549
2550 Status Registers
2551 \begin_inset LatexCommand \label{sec:stat-type}
2552
2553 \end_inset 
2554
2555
2556 \layout Standard
2557
2558 Each network interface maintains an array of status registers that can be
2559  accessed using the 
2560 \family typewriter 
2561 PtlNIStatus
2562 \family default 
2563  function (see Section\SpecialChar ~
2564
2565 \begin_inset LatexCommand \ref{sec:nistatus}
2566
2567 \end_inset 
2568
2569 ).
2570  The type 
2571 \family typewriter 
2572 ptl_sr_index_t
2573 \family default 
2574  defines the types of indexes that can be used to access the status registers.
2575  The only index defined for all implementations is 
2576 \family typewriter 
2577 PTL_SR_DROP_COUNT
2578 \family default 
2579  which identifies the status register that counts the dropped requests for
2580  the interface.
2581  Other indexes (and registers) may be defined by the implementation.
2582 \layout Standard
2583
2584 The type 
2585 \family typewriter 
2586 ptl_sr_value_t
2587 \family default 
2588  defines the types of values held in status registers.
2589  This is a signed integer type.
2590  The size is implementation dependent, but must be at least 32 bits.
2591 \layout Section
2592
2593 Initialization and Cleanup
2594 \begin_inset LatexCommand \label{sec:init}
2595
2596 \end_inset 
2597
2598
2599 \layout Standard
2600
2601 The Portals API includes a function, 
2602 \emph on 
2603 PtlInit
2604 \emph default 
2605 , to initialize the library and a function, 
2606 \emph on 
2607 PtlFini
2608 \emph default 
2609 , to cleanup after the application is done using the library.
2610 \layout Subsection
2611
2612 PtlInit
2613 \begin_inset LatexCommand \label{sec:ptlinit}
2614
2615 \end_inset 
2616
2617
2618 \layout LyX-Code
2619
2620 int PtlInit( int *max_interfaces );
2621 \layout Standard
2622 \noindent 
2623 The 
2624 \emph on 
2625 PtlInit
2626 \emph default 
2627  function initializes the Portals library.
2628  PtlInit must be called at least once by a process before any thread makes
2629  a Portals function call, but may be safely called more than once.
2630 \layout Subsubsection
2631
2632 Return Codes
2633 \layout Description
2634
2635 PTL_OK Indicates success.
2636  
2637 \layout Description
2638
2639 PTL_FAIL Indicates an error during initialization.
2640  
2641 \layout Description
2642
2643 PTL_SEGV Indicates that 
2644 \family typewriter 
2645 max_interfaces
2646 \family default 
2647  is not a legal address.
2648  
2649 \layout Subsubsection
2650
2651 Arguments
2652 \layout Standard
2653
2654
2655 \begin_inset  Tabular
2656 <lyxtabular version="3" rows="1" columns="3">
2657 <features>
2658 <column alignment="right" valignment="top" width="0pt">
2659 <column alignment="center" valignment="top" width="0pt">
2660 <column alignment="left" valignment="top" width="5in">
2661 <row>
2662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2663 \begin_inset Text
2664
2665 \layout Standard
2666
2667
2668 \family typewriter 
2669 max_interfaces
2670 \end_inset 
2671 </cell>
2672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2673 \begin_inset Text
2674
2675 \layout Standard
2676
2677
2678 \series bold 
2679 output
2680 \end_inset 
2681 </cell>
2682 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2683 \begin_inset Text
2684
2685 \layout Standard
2686 \noindent 
2687 On successful return, this location will hold the maximum number of interfaces
2688  that can be initialized.
2689 \end_inset 
2690 </cell>
2691 </row>
2692 </lyxtabular>
2693
2694 \end_inset 
2695
2696
2697 \layout Subsection
2698
2699 PtlFini
2700 \begin_inset LatexCommand \label{sec:ptlfini}
2701
2702 \end_inset 
2703
2704
2705 \layout LyX-Code
2706
2707 void PtlFini( void );
2708 \layout Standard
2709 \noindent 
2710 The 
2711 \emph on 
2712 PtlFini
2713 \emph default 
2714  function cleans up after the Portals library is no longer needed by a process.
2715  After this function is called, calls to any of the functions defined by
2716  the Portal API or use of the structures set up by the Portals API will
2717  result in undefined behavior.
2718  This function should be called once and only once during termination by
2719  a process.
2720  Typically, this function will be called in the exit sequence of a process.
2721  Individual threads should not call PtlFini when they terminate.
2722 \layout Section
2723
2724 Network Interfaces
2725 \begin_inset LatexCommand \label{sec:ni}
2726
2727 \end_inset 
2728
2729  
2730 \layout Standard
2731
2732 The Portals API supports the use of multiple network interfaces.
2733  However, each interface is treated as an independent entity.
2734  Combining interfaces (e.g., 
2735 \begin_inset Quotes eld
2736 \end_inset 
2737
2738 bonding
2739 \begin_inset Quotes erd
2740 \end_inset 
2741
2742  to create a higher bandwidth connection) must be implemented by the application
2743  or embedded in the underlying network.
2744  Interfaces are treated as independent entities to make it easier to cache
2745  information on individual network interface cards.
2746 \layout Standard
2747
2748 Once initialized, each interface provides a Portal table, an access control
2749  table, and a collection of status registers.
2750  See Section\SpecialChar ~
2751
2752 \begin_inset LatexCommand \ref{sec:me}
2753
2754 \end_inset 
2755
2756  for a discussion of updating Portal table entries using the 
2757 \emph on 
2758 PtlMEAttach
2759 \emph default 
2760  function.
2761  See Section\SpecialChar ~
2762
2763 \begin_inset LatexCommand \ref{sec:ac}
2764
2765 \end_inset 
2766
2767  for a discussion of the initialization and updating of entries in the access
2768  control table.
2769  See Section\SpecialChar ~
2770
2771 \begin_inset LatexCommand \ref{sec:nistatus}
2772
2773 \end_inset 
2774
2775  for a discussion of the 
2776 \emph on 
2777 PtlNIStatus
2778 \emph default 
2779  function which can be used to determine the value of a status register.
2780 \layout Standard
2781
2782 Every other type of Portal object (e.g., memory descriptor, event queue, or
2783  match list entry) is associated with a specific network interface.
2784  The association to a network interface is established when the object is
2785  created and is encoded in the handle for the object.
2786 \layout Standard
2787
2788 Each network interface is initialized and shutdown independently.
2789  The initialization routine, 
2790 \emph on 
2791 PtlNIInit
2792 \emph default 
2793 , returns a handle for an interface object which is used in all subsequent
2794  Portal operations.
2795  The 
2796 \emph on 
2797 PtlNIFini
2798 \emph default 
2799  function is used to shutdown an interface and release any resources that
2800  are associated with the interface.
2801  Network interface handles are associated with processes, not threads.
2802  All threads in a process share all of the network interface handles.
2803 \layout Standard
2804
2805 The Portals API also defines the 
2806 \emph on 
2807 PtlNIStatus
2808 \emph default 
2809  function to query the status registers for a network interface, the 
2810 \emph on 
2811 PtlNIDist
2812 \emph default 
2813  function to determine the 
2814 \begin_inset Quotes eld
2815 \end_inset 
2816
2817 distance
2818 \begin_inset Quotes erd
2819 \end_inset 
2820
2821  to another process, and the 
2822 \emph on 
2823 PtlNIHandle
2824 \emph default 
2825  function to determine the network interface that an object is associated
2826  with.
2827 \layout Subsection
2828
2829 PtlNIInit
2830 \begin_inset LatexCommand \label{sec:niinit}
2831
2832 \end_inset 
2833
2834
2835 \layout LyX-Code
2836
2837 typedef struct {
2838 \newline 
2839     int            max_match_entries;
2840 \newline 
2841     int            max_mem_descriptors;
2842 \newline 
2843     int            max_event_queues;
2844 \newline 
2845     ptl_ac_index_t max_atable_index; 
2846 \newline 
2847     ptl_pt_index_t max_ptable_index;
2848 \newline 
2849 } ptl_ni_limits_t;
2850 \newline 
2851
2852 \newline 
2853 int PtlNIInit( ptl_interface_t  interface
2854 \newline 
2855                ptl_pid_t        pid,
2856 \newline 
2857                ptl_ni_limits_t* desired,
2858 \newline 
2859                ptl_ni_limits_t* actual,
2860 \newline 
2861                ptl_handle_ni_t* handle );
2862 \layout Standard
2863
2864 Values of type 
2865 \family typewriter 
2866 ptl_ni_limits_t
2867 \family default 
2868  include the following members:
2869 \layout Description
2870
2871 max_match_entries Maximum number of match entries that can be allocated
2872  at any one time.
2873 \layout Description
2874
2875 max_mem_descriptors Maximum number of memory descriptors that can be allocated
2876  at any one time.
2877 \layout Description
2878
2879 max_event_queues Maximum number of event queues that can be allocated at
2880  any one time.
2881 \layout Description
2882
2883 max_atable_index Largest access control table index for this interface,
2884  valid indexes range from zero to 
2885 \family typewriter 
2886 max_atable_index
2887 \family default 
2888 , inclusive.
2889 \layout Description
2890
2891 max_ptable_index Largest Portal table index for this interface, valid indexes
2892  range from zero to 
2893 \family typewriter 
2894 max_ptable_index
2895 \family default 
2896 , inclusive.
2897 \layout Standard
2898 \noindent 
2899 The 
2900 \emph on 
2901 PtlNIInit
2902 \emph default 
2903  function is used to initialized the Portals API for a network interface.
2904  This function must be called at least once by each process before any other
2905  operations that apply to the interface by any process or thread.
2906  For subsequent calls to 
2907 \shape italic 
2908 PtlNIInit
2909 \shape default 
2910  from within the same process (either by different threads or the same thread),
2911  the desired limits will be ignored and the call will return the existing
2912  NI handle.
2913 \layout Subsubsection
2914
2915 Return Codes
2916 \layout Description
2917
2918 PTL_OK Indicates success.
2919  
2920 \layout Description
2921
2922 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
2923  
2924 \layout Description
2925
2926 PTL_INIT_DUP Indicates a duplicate initialization of 
2927 \family typewriter 
2928 interface
2929 \family default 
2930 .
2931  
2932 \layout Description
2933
2934 PTL_INIT_INV Indicates that 
2935 \family typewriter 
2936 interface
2937 \family default 
2938  is not a valid network interface.
2939  
2940 \layout Description
2941
2942 PTL_NOSPACE Indicates that there is insufficient memory to initialize the
2943  interface.
2944  
2945 \layout Description
2946
2947 PTL_INV_PROC Indicates that 
2948 \family typewriter 
2949 pid
2950 \family default 
2951  is not a valid process id.
2952 \layout Description
2953
2954 PTL_SEGV Indicates that 
2955 \family typewriter 
2956 actual 
2957 \family default 
2958 or
2959 \family typewriter 
2960  handle
2961 \family default 
2962  is not a legal address.
2963  
2964 \layout Subsubsection
2965
2966 Arguments
2967 \layout Standard
2968
2969
2970 \begin_inset  Tabular
2971 <lyxtabular version="3" rows="5" columns="3">
2972 <features>
2973 <column alignment="right" valignment="top" width="0pt">
2974 <column alignment="center" valignment="top" width="0pt">
2975 <column alignment="left" valignment="top" width="4.7in">
2976 <row>
2977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2978 \begin_inset Text
2979
2980 \layout Standard
2981
2982
2983 \family typewriter 
2984 interface
2985 \end_inset 
2986 </cell>
2987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2988 \begin_inset Text
2989
2990 \layout Standard
2991
2992
2993 \series bold 
2994 input
2995 \end_inset 
2996 </cell>
2997 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2998 \begin_inset Text
2999
3000 \layout Standard
3001 \noindent 
3002 Identifies the network interface to be initialized.
3003   (See section\SpecialChar ~
3004
3005 \begin_inset LatexCommand \ref{sec:ni-type}
3006
3007 \end_inset 
3008
3009  for a discussion of  values used to identify network interfaces.)
3010 \end_inset 
3011 </cell>
3012 </row>
3013 <row>
3014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3015 \begin_inset Text
3016
3017 \layout Standard
3018
3019
3020 \family typewriter 
3021 pid
3022 \end_inset 
3023 </cell>
3024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3025 \begin_inset Text
3026
3027 \layout Standard
3028
3029
3030 \series bold 
3031 input
3032 \end_inset 
3033 </cell>
3034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3035 \begin_inset Text
3036
3037 \layout Standard
3038 \noindent 
3039 Identifies the desired process id (for well known process ids).
3040  The value 
3041 \family typewriter 
3042 PTL_PID_ANY
3043 \family default 
3044  may be used to have the process id assigned by the underlying library.
3045 \end_inset 
3046 </cell>
3047 </row>
3048 <row>
3049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3050 \begin_inset Text
3051
3052 \layout Standard
3053
3054
3055 \family typewriter 
3056 desired
3057 \end_inset 
3058 </cell>
3059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3060 \begin_inset Text
3061
3062 \layout Standard
3063
3064
3065 \series bold 
3066 input
3067 \end_inset 
3068 </cell>
3069 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3070 \begin_inset Text
3071
3072 \layout Standard
3073 \noindent 
3074 If non-NULL, points to a structure that holds the desired limits.
3075 \end_inset 
3076 </cell>
3077 </row>
3078 <row>
3079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3080 \begin_inset Text
3081
3082 \layout Standard
3083
3084
3085 \family typewriter 
3086 actual
3087 \end_inset 
3088 </cell>
3089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3090 \begin_inset Text
3091
3092 \layout Standard
3093
3094
3095 \series bold 
3096 output
3097 \end_inset 
3098 </cell>
3099 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3100 \begin_inset Text
3101
3102 \layout Standard
3103 \noindent 
3104 On successful return, the location pointed to by actual will hold the actual
3105  limits.
3106 \end_inset 
3107 </cell>
3108 </row>
3109 <row>
3110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3111 \begin_inset Text
3112
3113 \layout Standard
3114
3115
3116 \family typewriter 
3117 handle
3118 \end_inset 
3119 </cell>
3120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125
3126 \series bold 
3127 output
3128 \end_inset 
3129 </cell>
3130 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3131 \begin_inset Text
3132
3133 \layout Standard
3134 \noindent 
3135 On successful return, this location will hold a  handle for the interface.
3136 \end_inset 
3137 </cell>
3138 </row>
3139 </lyxtabular>
3140
3141 \end_inset 
3142
3143
3144 \layout Comment
3145
3146 The use of desired is implementation dependent.
3147  In particular, an implementation may choose to ignore this argument.
3148 \layout Subsection
3149
3150 PtlNIFini
3151 \begin_inset LatexCommand \label{sec:nifini}
3152
3153 \end_inset 
3154
3155
3156 \layout LyX-Code
3157
3158 int PtlNIFini( ptl_handle_ni_t interface );
3159 \layout Standard
3160 \noindent 
3161 The 
3162 \emph on 
3163 PtlNIFini
3164 \emph default 
3165  function is used to release the resources allocated for a network interface.
3166  Once the 
3167 \emph on 
3168 PtlNIFini
3169 \emph default 
3170  operation has been started, the results of pending API operations (e.g.,
3171  operations initiated by another thread) for this interface are undefined.
3172  Similarly, the effects of incoming operations (puts and gets) or return
3173  values (acknowledgements and replies) for this interface are undefined.
3174 \layout Subsubsection
3175
3176 Return Codes
3177 \layout Description
3178
3179 PTL_OK Indicates success.
3180  
3181 \layout Description
3182
3183 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3184  
3185 \layout Description
3186
3187 PTL_INV_NI Indicates that 
3188 \family typewriter 
3189 interface
3190 \family default 
3191  is not a valid network interface handle.
3192  
3193 \layout Subsubsection
3194
3195 Arguments
3196 \layout Standard
3197
3198
3199 \begin_inset  Tabular
3200 <lyxtabular version="3" rows="1" columns="3">
3201 <features>
3202 <column alignment="right" valignment="top" width="0pt">
3203 <column alignment="center" valignment="top" width="0pt">
3204 <column alignment="center" valignment="top" width="0pt">
3205 <row>
3206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3207 \begin_inset Text
3208
3209 \layout Standard
3210
3211 interface
3212 \end_inset 
3213 </cell>
3214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3215 \begin_inset Text
3216
3217 \layout Standard
3218
3219
3220 \series bold 
3221 input
3222 \end_inset 
3223 </cell>
3224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3225 \begin_inset Text
3226
3227 \layout Standard
3228
3229 A handle for the interface to shutdown.
3230 \end_inset 
3231 </cell>
3232 </row>
3233 </lyxtabular>
3234
3235 \end_inset 
3236
3237
3238 \layout Subsection
3239
3240 PtlNIStatus
3241 \begin_inset LatexCommand \label{sec:nistatus}
3242
3243 \end_inset 
3244
3245
3246 \layout LyX-Code
3247
3248 int PtlNIStatus( ptl_handle_ni_t interface,
3249 \newline 
3250                  ptl_sr_index_t  status_register,
3251 \newline 
3252                  ptl_sr_value_t* status );
3253 \layout Standard
3254 \noindent 
3255 The 
3256 \emph on 
3257 PtlNIStatus
3258 \emph default 
3259  function returns the value of a status register for the specified interface.
3260  (See section\SpecialChar ~
3261
3262 \begin_inset LatexCommand \ref{sec:stat-type}
3263
3264 \end_inset 
3265
3266  for more information on status register indexes and status register values.)
3267 \layout Subsubsection
3268
3269 Return Codes
3270 \layout Description
3271
3272 PTL_OK Indicates success.
3273  
3274 \layout Description
3275
3276 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3277  
3278 \layout Description
3279
3280 PTL_INV_NI Indicates that 
3281 \family typewriter 
3282 interface
3283 \family default 
3284  is not a valid network interface handle.
3285  
3286 \layout Description
3287
3288 PTL_INV_SR_INDX Indicates that 
3289 \family typewriter 
3290 status_register
3291 \family default 
3292  is not a valid status register.
3293  
3294 \layout Description
3295
3296 PTL_SEGV Indicates that 
3297 \family typewriter 
3298 status
3299 \family default 
3300  is not a legal address.
3301  
3302 \layout Subsubsection
3303
3304 Arguments
3305 \layout Standard
3306
3307
3308 \begin_inset  Tabular
3309 <lyxtabular version="3" rows="3" columns="3">
3310 <features>
3311 <column alignment="right" valignment="top" width="0pt">
3312 <column alignment="center" valignment="top" width="0pt">
3313 <column alignment="left" valignment="top" width="4.7in">
3314 <row>
3315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3316 \begin_inset Text
3317
3318 \layout Standard
3319
3320
3321 \family typewriter 
3322 interface
3323 \end_inset 
3324 </cell>
3325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3326 \begin_inset Text
3327
3328 \layout Standard
3329
3330
3331 \series bold 
3332 input
3333 \end_inset 
3334 </cell>
3335 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3336 \begin_inset Text
3337
3338 \layout Standard
3339 \noindent 
3340 A handle for the interface to use.
3341  
3342 \end_inset 
3343 </cell>
3344 </row>
3345 <row>
3346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3347 \begin_inset Text
3348
3349 \layout Standard
3350
3351
3352 \family typewriter 
3353 status_register
3354 \end_inset 
3355 </cell>
3356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3357 \begin_inset Text
3358
3359 \layout Standard
3360
3361
3362 \series bold 
3363 input
3364 \end_inset 
3365 </cell>
3366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3367 \begin_inset Text
3368
3369 \layout Standard
3370 \noindent 
3371 An index for the status register to read.
3372 \end_inset 
3373 </cell>
3374 </row>
3375 <row>
3376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3377 \begin_inset Text
3378
3379 \layout Standard
3380
3381
3382 \family typewriter 
3383 status
3384 \end_inset 
3385 </cell>
3386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3387 \begin_inset Text
3388
3389 \layout Standard
3390
3391
3392 \series bold 
3393 output
3394 \end_inset 
3395 </cell>
3396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3397 \begin_inset Text
3398
3399 \layout Standard
3400 \noindent 
3401 On successful return, this location will hold the current value of the status
3402  register.
3403 \end_inset 
3404 </cell>
3405 </row>
3406 </lyxtabular>
3407
3408 \end_inset 
3409
3410
3411 \layout Comment
3412
3413 The only status register that must be defined is a drop count register (
3414 \family typewriter 
3415 PTL_SR_DROP_COUNT
3416 \family default 
3417 ).
3418  Implementations may define additional status registers.
3419  Identifiers for the indexes associated with these registers should start
3420  with the prefix 
3421 \family typewriter 
3422 PTL_SR_
3423 \family default 
3424 .
3425 \layout Subsection
3426
3427 PtlNIDist
3428 \layout LyX-Code
3429
3430 int PtlNIDist( ptl_handle_ni_t  interface,
3431 \newline 
3432                ptl_process_id_t process,
3433 \newline 
3434                unsigned long*   distance );
3435 \layout Standard
3436 \noindent 
3437 The 
3438 \emph on 
3439 PtlNIDist
3440 \emph default 
3441  function returns the distance to another process using the specified interface.
3442  Distances are only defined relative to an interface.
3443  Distance comparisons between different interfaces on the same process may
3444  be meaningless.
3445 \layout Subsubsection
3446
3447 Return Codes
3448 \layout Description
3449
3450 PTL_OK Indicates success.
3451  
3452 \layout Description
3453
3454 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3455  
3456 \layout Description
3457
3458 PTL_INV_NI Indicates that 
3459 \family typewriter 
3460 interface
3461 \family default 
3462  is not a valid network interface handle.
3463  
3464 \layout Description
3465
3466 PTL_INV_PROC Indicates that 
3467 \family typewriter 
3468 process
3469 \family default 
3470  is not a valid process identifier.
3471  
3472 \layout Description
3473
3474 PTL_SEGV Indicates that 
3475 \family typewriter 
3476 distance
3477 \family default 
3478  is not a legal address.
3479  
3480 \layout Subsubsection
3481
3482 Arguments
3483 \layout Standard
3484
3485
3486 \begin_inset  Tabular
3487 <lyxtabular version="3" rows="3" columns="3">
3488 <features>
3489 <column alignment="right" valignment="top" width="0pt">
3490 <column alignment="center" valignment="top" width="0pt">
3491 <column alignment="left" valignment="top" width="4.7in">
3492 <row>
3493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3494 \begin_inset Text
3495
3496 \layout Standard
3497
3498
3499 \family typewriter 
3500 interface
3501 \end_inset 
3502 </cell>
3503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3504 \begin_inset Text
3505
3506 \layout Standard
3507
3508
3509 \series bold 
3510 input
3511 \end_inset 
3512 </cell>
3513 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3514 \begin_inset Text
3515
3516 \layout Standard
3517 \noindent 
3518 A handle for the interface to use.
3519  
3520 \end_inset 
3521 </cell>
3522 </row>
3523 <row>
3524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3525 \begin_inset Text
3526
3527 \layout Standard
3528
3529
3530 \family typewriter 
3531 process
3532 \end_inset 
3533 </cell>
3534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3535 \begin_inset Text
3536
3537 \layout Standard
3538
3539
3540 \series bold 
3541 input
3542 \end_inset 
3543 </cell>
3544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3545 \begin_inset Text
3546
3547 \layout Standard
3548 \noindent 
3549 An identifier for the process whose distance is being  requested.
3550  
3551 \end_inset 
3552 </cell>
3553 </row>
3554 <row>
3555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3556 \begin_inset Text
3557
3558 \layout Standard
3559
3560
3561 \family typewriter 
3562 distance
3563 \end_inset 
3564 </cell>
3565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3566 \begin_inset Text
3567
3568 \layout Standard
3569
3570
3571 \series bold 
3572 output
3573 \end_inset 
3574 </cell>
3575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3576 \begin_inset Text
3577
3578 \layout Standard
3579 \noindent 
3580 On successful return, this location will hold the  distance to the remote
3581  process.
3582 \end_inset 
3583 </cell>
3584 </row>
3585 </lyxtabular>
3586
3587 \end_inset 
3588
3589
3590 \layout Comment
3591
3592 This function should return a static measure of distance.
3593  Examples include minimum latency, the inverse of available bandwidth, or
3594  the number of switches between the two endpoints.
3595 \layout Subsection
3596
3597 PtlNIHandle
3598 \layout LyX-Code
3599
3600 int PtlNIHandle( ptl_handle_any_t handle,
3601 \newline 
3602                  ptl_handle_ni_t* interface );
3603 \layout Standard
3604 \noindent 
3605 The 
3606 \emph on 
3607 PtlNIHandle
3608 \emph default 
3609  function returns a handle for the network interface with which the object
3610  identified by 
3611 \family typewriter 
3612 handle
3613 \family default 
3614  is associated.
3615  If the object identified by 
3616 \family typewriter 
3617 handle
3618 \family default 
3619  is a network interface, this function returns the same value it is passed.
3620 \layout Subsubsection
3621
3622 Return Codes
3623 \layout Description
3624
3625 PTL_OK Indicates success.
3626  
3627 \layout Description
3628
3629 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3630  
3631 \layout Description
3632
3633 PTL_INV_HANDLE Indicates that 
3634 \family typewriter 
3635 handle
3636 \family default 
3637  is not a valid handle.
3638  
3639 \layout Description
3640
3641 PTL_SEGV Indicates that 
3642 \family typewriter 
3643 interface
3644 \family default 
3645  is not a legal address.
3646  
3647 \layout Subsubsection
3648
3649 Arguments
3650 \layout Standard
3651
3652
3653 \begin_inset  Tabular
3654 <lyxtabular version="3" rows="2" columns="3">
3655 <features>
3656 <column alignment="right" valignment="top" width="0pt">
3657 <column alignment="center" valignment="top" width="0pt">
3658 <column alignment="left" valignment="top" width="4.7in">
3659 <row>
3660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3661 \begin_inset Text
3662
3663 \layout Standard
3664
3665
3666 \family typewriter 
3667 handle
3668 \end_inset 
3669 </cell>
3670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3671 \begin_inset Text
3672
3673 \layout Standard
3674
3675
3676 \series bold 
3677 input
3678 \end_inset 
3679 </cell>
3680 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3681 \begin_inset Text
3682
3683 \layout Standard
3684 \noindent 
3685 A handle for the object.
3686 \end_inset 
3687 </cell>
3688 </row>
3689 <row>
3690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3691 \begin_inset Text
3692
3693 \layout Standard
3694
3695
3696 \family typewriter 
3697 interface
3698 \end_inset 
3699 </cell>
3700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3701 \begin_inset Text
3702
3703 \layout Standard
3704
3705
3706 \series bold 
3707 output
3708 \end_inset 
3709 </cell>
3710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3711 \begin_inset Text
3712
3713 \layout Standard
3714 \noindent 
3715 On successful return, this location will hold a handle for the network interface
3716  associated with 
3717 \family typewriter 
3718 handle
3719 \family default 
3720 .
3721 \end_inset 
3722 </cell>
3723 </row>
3724 </lyxtabular>
3725
3726 \end_inset 
3727
3728
3729 \layout Comment
3730
3731 Every handle should encode the network interface and the object id relative
3732  to this handle.
3733  Both are presumably encoded using integer values.
3734 \layout Section
3735
3736 User Identification
3737 \begin_inset LatexCommand \label{sec:uid}
3738
3739 \end_inset 
3740
3741
3742 \layout Standard
3743
3744 Every process runs on behalf of a user.
3745  
3746 \layout Subsection
3747
3748 PtlGetUid
3749 \layout LyX-Code
3750
3751 int PtlGetUid( ptl_handle_ni_t   ni_handle,
3752 \newline 
3753                ptl_uid_t*        uid );
3754 \layout Subsubsection
3755
3756 Return Codes
3757 \layout Description
3758
3759 PTL_OK Indicates success.
3760  
3761 \layout Description
3762
3763 PTL_INV_NI Indicates that 
3764 \family typewriter 
3765 ni_handle
3766 \family default 
3767  is not a valid network interface handle.
3768  
3769 \layout Description
3770
3771 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3772  
3773 \layout Description
3774
3775 PTL_SEGV Indicates that 
3776 \family typewriter 
3777 interface
3778 \family default 
3779  is not a legal address.
3780  
3781 \layout Subsubsection
3782
3783 Arguments
3784 \layout Standard
3785
3786
3787 \begin_inset  Tabular
3788 <lyxtabular version="3" rows="2" columns="3">
3789 <features>
3790 <column alignment="right" valignment="top" width="0pt">
3791 <column alignment="center" valignment="top" width="0pt">
3792 <column alignment="left" valignment="top" width="5in">
3793 <row>
3794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3795 \begin_inset Text
3796
3797 \layout Standard
3798
3799
3800 \family typewriter 
3801 handle
3802 \end_inset 
3803 </cell>
3804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3805 \begin_inset Text
3806
3807 \layout Standard
3808
3809
3810 \series bold 
3811 input
3812 \end_inset 
3813 </cell>
3814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3815 \begin_inset Text
3816
3817 \layout Standard
3818 \noindent 
3819 A network interface handle.
3820 \end_inset 
3821 </cell>
3822 </row>
3823 <row>
3824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3825 \begin_inset Text
3826
3827 \layout Standard
3828
3829
3830 \family typewriter 
3831 id
3832 \end_inset 
3833 </cell>
3834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3835 \begin_inset Text
3836
3837 \layout Standard
3838
3839
3840 \series bold 
3841 output
3842 \end_inset 
3843 </cell>
3844 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3845 \begin_inset Text
3846
3847 \layout Standard
3848 \noindent 
3849 On successful return, this location will hold the user id for the calling
3850  process.
3851 \end_inset 
3852 </cell>
3853 </row>
3854 </lyxtabular>
3855
3856 \end_inset 
3857
3858
3859 \layout Comment
3860
3861 Note that user identifiers are dependent on the network interface(s).
3862  In particular, if a node has multiple interfaces, a process may have multiple
3863  user identifiers.
3864 \layout Section
3865
3866 Process Identification
3867 \begin_inset LatexCommand \label{sec:pid}
3868
3869 \end_inset 
3870
3871
3872 \layout Standard
3873
3874 Processes that use the Portals API, can be identified using a node id and
3875  process id.
3876  Every node accessible through a network interface has a unique node identifier
3877  and every process running on a node has a unique process identifier.
3878  As such, any process in the computing system can be identified by its node
3879  id and process id.
3880  
3881 \layout Standard
3882
3883 The Portals API defines a type, 
3884 \family typewriter 
3885 ptl_process_id_t
3886 \family default 
3887  for representing process ids and a function, 
3888 \emph on 
3889 PtlGetId
3890 \emph default 
3891 , which can be used to obtain the id of the current process.
3892 \layout Comment
3893
3894 The portals API does not include thread identifiers.
3895   Messages are delivered to processes (address spaces) not threads (contexts
3896  of  execution).
3897 \layout Subsection
3898
3899 The Process Id Type
3900 \begin_inset LatexCommand \label{sec:pid-type}
3901
3902 \end_inset 
3903
3904
3905 \layout LyX-Code
3906
3907 typedef struct {
3908 \newline 
3909     ptl_nid_t       nid; /* node id */
3910 \newline 
3911     ptl_pid_t       pid; /* process id */
3912 \newline 
3913 } ptl_process_id_t;
3914 \layout Standard
3915 \noindent 
3916 The 
3917 \family typewriter 
3918 ptl_process_id_t
3919 \family default 
3920  type uses two identifiers to represent a process id: a node id and a process
3921  id.
3922  
3923 \layout Subsection
3924
3925 PtlGetId
3926 \begin_inset LatexCommand \label{sub:PtlGetId}
3927
3928 \end_inset 
3929
3930
3931 \layout LyX-Code
3932
3933 int PtlGetId( ptl_handle_ni_t   ni_handle,
3934 \newline 
3935               ptl_process_id_t* id );
3936 \layout Subsubsection
3937
3938 Return Codes
3939 \layout Description
3940
3941 PTL_OK Indicates success.
3942  
3943 \layout Description
3944
3945 PTL_INV_NI Indicates that 
3946 \family typewriter 
3947 ni_handle
3948 \family default 
3949  is not a valid network interface handle.
3950  
3951 \layout Description
3952
3953 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3954  
3955 \layout Description
3956
3957 PTL_SEGV Indicates that 
3958 \family typewriter 
3959 id
3960 \family default 
3961  is not a legal address.
3962  
3963 \layout Subsubsection
3964
3965 Arguments
3966 \layout Standard
3967
3968
3969 \begin_inset  Tabular
3970 <lyxtabular version="3" rows="2" columns="3">
3971 <features>
3972 <column alignment="right" valignment="top" width="0pt">
3973 <column alignment="center" valignment="top" width="0pt">
3974 <column alignment="left" valignment="top" width="5in">
3975 <row>
3976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3977 \begin_inset Text
3978
3979 \layout Standard
3980
3981
3982 \family typewriter 
3983 handle
3984 \end_inset 
3985 </cell>
3986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3987 \begin_inset Text
3988
3989 \layout Standard
3990
3991
3992 \series bold 
3993 input
3994 \end_inset 
3995 </cell>
3996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3997 \begin_inset Text
3998
3999 \layout Standard
4000 \noindent 
4001 A network interface handle.
4002 \end_inset 
4003 </cell>
4004 </row>
4005 <row>
4006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4007 \begin_inset Text
4008
4009 \layout Standard
4010
4011
4012 \family typewriter 
4013 id
4014 \end_inset 
4015 </cell>
4016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4017 \begin_inset Text
4018
4019 \layout Standard
4020
4021
4022 \series bold 
4023 output
4024 \end_inset 
4025 </cell>
4026 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4027 \begin_inset Text
4028
4029 \layout Standard
4030 \noindent 
4031 On successful return, this location will hold the id for the calling process.
4032 \end_inset 
4033 </cell>
4034 </row>
4035 </lyxtabular>
4036
4037 \end_inset 
4038
4039
4040 \layout Comment
4041
4042 Note that process identifiers are dependent on the network interface(s).
4043  In particular, if a node has multiple interfaces, it may have multiple
4044  node identifiers.
4045 \layout Section
4046
4047 Match List Entries and Match Lists
4048 \begin_inset LatexCommand \label{sec:me}
4049
4050 \end_inset 
4051
4052
4053 \layout Standard
4054
4055 A match list is a chain of match list entries.
4056  Each match list entry includes a memory descriptor and a set of match criteria.
4057  The match criteria can be used to reject incoming requests based on process
4058  id or the match bits provided in the request.
4059  A match list is created using the 
4060 \emph on 
4061 PtlMEAttach
4062 \emph default 
4063  or 
4064 \shape italic 
4065 PtlMEAttachAny
4066 \shape default 
4067  functions, which create a match list consisting of a single match list
4068  entry, attaches the match list to the specified Portal index, and returns
4069  a handle for the match list entry.
4070  Match entries can be dynamically inserted and removed from a match list
4071  using the 
4072 \emph on 
4073 PtlMEInsert
4074 \emph default 
4075  and 
4076 \emph on 
4077 PtlMEUnlink
4078 \emph default 
4079  functions.
4080 \layout Subsection
4081
4082 PtlMEAttach
4083 \begin_inset LatexCommand \label{sec:meattach}
4084
4085 \end_inset 
4086
4087
4088 \layout LyX-Code
4089
4090 typedef enum { PTL_RETAIN, PTL_UNLINK } ptl_unlink_t;
4091 \newline 
4092
4093 \layout LyX-Code
4094
4095 typedef enum { PTL_INS_BEFORE, PTL_INS_AFTER } ptl_ins_pos_t;
4096 \newline 
4097
4098 \layout LyX-Code
4099
4100 int PtlMEAttach( ptl_handle_ni_t  interface,
4101 \newline 
4102                  ptl_pt_index_t   index,
4103 \newline 
4104                  ptl_process_id_t matchid,
4105 \newline 
4106                  ptl_match_bits_t match_bits,
4107 \newline 
4108                  ptl_match_bits_t ignorebits,
4109 \newline 
4110                  ptl_unlink_t     unlink,
4111 \newline 
4112                  ptl_ins_pos_t    position,
4113 \newline 
4114                  ptl_handle_me_t* handle );
4115 \layout Standard
4116 \noindent 
4117 Values of the type 
4118 \family typewriter 
4119 ptl_ins_pos_t
4120 \family default 
4121  are used to control where a new item is inserted.
4122  The value 
4123 \family typewriter 
4124 PTL_INS_BEFORE
4125 \family default 
4126  is used to insert the new item before the current item or before the head
4127  of the list.
4128  The value 
4129 \family typewriter 
4130 PTL_INS_AFTER
4131 \family default 
4132  is used to insert the new item after the current item or after the last
4133  item in the list.
4134  
4135 \layout Standard
4136
4137 The 
4138 \emph on 
4139 PtlMEAttach
4140 \emph default 
4141  function creates a match list consisting of a single entry and attaches
4142  this list to the Portal table for 
4143 \family typewriter 
4144 interface
4145 \family default 
4146 .
4147 \layout Subsubsection
4148
4149 Return Codes
4150 \layout Description
4151
4152 PTL_OK Indicates success.
4153  
4154 \layout Description
4155
4156 PTL_INV_NI Indicates that 
4157 \family typewriter 
4158 interface
4159 \family default 
4160  is not a valid network interface handle.
4161  
4162 \layout Description
4163
4164 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
4165  
4166 \layout Description
4167
4168 PTL_INV_PTINDEX Indicates that 
4169 \family typewriter 
4170 index
4171 \family default 
4172  is not a valid Portal table index.
4173  
4174 \layout Description
4175
4176 PTL_INV_PROC Indicates that 
4177 \family typewriter 
4178 matchid
4179 \family default 
4180  is not a valid process identifier.
4181  
4182 \layout Description
4183
4184 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
4185  match list entry.
4186  
4187 \layout Description
4188
4189 PTL_ML_TOOLONG Indicates that the resulting match list is too long.
4190  The maximum length for a match list is defined by the interface.
4191  
4192 \layout Subsubsection
4193
4194 Arguments
4195 \layout Standard
4196
4197
4198 \begin_inset  Tabular
4199 <lyxtabular version="3" rows="7" columns="3">
4200 <features>
4201 <column alignment="left" valignment="top" width="0.8in">
4202 <column alignment="center" valignment="top" width="0pt">
4203 <column alignment="left" valignment="top" width="4.75in">
4204 <row>
4205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4206 \begin_inset Text
4207
4208 \layout Standard
4209 \noindent 
4210
4211 \family typewriter 
4212 interface
4213 \end_inset 
4214 </cell>
4215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4216 \begin_inset Text
4217
4218 \layout Standard
4219
4220
4221 \series bold 
4222 input
4223 \end_inset 
4224 </cell>
4225 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4226 \begin_inset Text
4227
4228 \layout Standard
4229 \noindent 
4230 A handle for the interface to use.
4231  
4232 \end_inset 
4233 </cell>
4234 </row>
4235 <row>
4236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4237 \begin_inset Text
4238
4239 \layout Standard
4240 \noindent 
4241
4242 \family typewriter 
4243 index
4244 \end_inset 
4245 </cell>
4246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4247 \begin_inset Text
4248
4249 \layout Standard
4250
4251
4252 \series bold 
4253 input
4254 \end_inset 
4255 </cell>
4256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4257 \begin_inset Text
4258
4259 \layout Standard
4260 \noindent 
4261 The Portal table index where the match list  should be attached.
4262 \end_inset 
4263 </cell>
4264 </row>
4265 <row>
4266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4267 \begin_inset Text
4268
4269 \layout Standard
4270 \noindent 
4271
4272 \family typewriter 
4273 matchid
4274 \end_inset 
4275 </cell>
4276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4277 \begin_inset Text
4278
4279 \layout Standard
4280
4281
4282 \series bold 
4283 input
4284 \end_inset 
4285 </cell>
4286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4287 \begin_inset Text
4288
4289 \layout Standard
4290 \noindent 
4291 Specifies the match criteria for the process id of the requestor.
4292   The constants 
4293 \family typewriter 
4294 PTL_PID_ANY
4295 \family default 
4296  and 
4297 \family typewriter 
4298 PTL_NID_ANY
4299 \family default 
4300  can be used to  wildcard either of the ids in the 
4301 \family typewriter 
4302 ptl_process_id_t
4303 \family default 
4304  structure.
4305  
4306 \end_inset 
4307 </cell>
4308 </row>
4309 <row>
4310 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4311 \begin_inset Text
4312
4313 \layout Standard
4314 \noindent 
4315
4316 \family typewriter 
4317 match_bits, ignorebits
4318 \end_inset 
4319 </cell>
4320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4321 \begin_inset Text
4322
4323 \layout Standard
4324
4325
4326 \series bold 
4327 input
4328 \end_inset 
4329 </cell>
4330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4331 \begin_inset Text
4332
4333 \layout Standard
4334 \noindent 
4335 Specify the match criteria to apply  to the match bits in the incoming request.
4336   The 
4337 \family typewriter 
4338 ignorebits
4339 \family default 
4340  are used to mask out insignificant bits in the incoming match bits.
4341   The resulting bits are then compared to the match list entry's match 
4342  bits to determine if the incoming request meets the match criteria.
4343 \end_inset 
4344 </cell>
4345 </row>
4346 <row>
4347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4348 \begin_inset Text
4349
4350 \layout Standard
4351 \noindent 
4352
4353 \family typewriter 
4354 unlink
4355 \end_inset 
4356 </cell>
4357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4358 \begin_inset Text
4359
4360 \layout Standard
4361
4362
4363 \series bold 
4364 input
4365 \end_inset 
4366 </cell>
4367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4368 \begin_inset Text
4369
4370 \layout Standard
4371 \noindent 
4372 Indicates the match list entry should be unlinked when the last memory descripto
4373 r associated with this match list  entry is unlinked.
4374   (Note, the check for unlinking a match entry  only occurs when a memory
4375  descriptor is unlinked.) 
4376 \end_inset 
4377 </cell>
4378 </row>
4379 <row>
4380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4381 \begin_inset Text
4382
4383 \layout Standard
4384 \noindent 
4385
4386 \family typewriter 
4387 position
4388 \end_inset 
4389 </cell>
4390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4391 \begin_inset Text
4392
4393 \layout Standard
4394
4395
4396 \series bold 
4397 input
4398 \end_inset 
4399 </cell>
4400 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4401 \begin_inset Text
4402
4403 \layout Standard
4404 \noindent 
4405 Indicates whether the new match entry should be prepended or appended to
4406  the existing match list.
4407  If there is no existing list, this argument is ignored and the new match
4408  entry becomes the only entry in the list.
4409  Allowed constants: 
4410 \family typewriter 
4411 PTL_INS_BEFORE
4412 \family default 
4413
4414 \family typewriter 
4415 PTL_INS_AFTER
4416 \family default 
4417 .
4418 \end_inset 
4419 </cell>
4420 </row>
4421 <row>
4422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4423 \begin_inset Text
4424
4425 \layout Standard
4426 \noindent 
4427
4428 \family typewriter 
4429 handle
4430 \end_inset 
4431 </cell>
4432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4433 \begin_inset Text
4434
4435 \layout Standard
4436
4437
4438 \series bold 
4439 output
4440 \end_inset 
4441 </cell>
4442 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4443 \begin_inset Text
4444
4445 \layout Standard
4446 \noindent 
4447 On successful return, this location will hold a  handle for the newly created
4448  match list entry.
4449 \end_inset 
4450 </cell>
4451 </row>
4452 </lyxtabular>
4453
4454 \end_inset 
4455
4456
4457 \layout Subsection
4458
4459 PtlMEAttachAny
4460 \begin_inset LatexCommand \label{sec:attachany}
4461
4462 \end_inset 
4463
4464
4465 \layout LyX-Code
4466
4467 int PtlMEAttachAny( ptl_handle_ni_t  interface,
4468 \newline 
4469                     ptl_pt_index_t   *index,
4470 \newline 
4471                     ptl_process_id_t matchid,
4472 \newline 
4473                     ptl_match_bits_t match_bits,
4474 \newline 
4475                     ptl_match_bits_t ignorebits,
4476 \newline 
4477                     ptl_unlink_t     unlink,
4478 \newline 
4479                     ptl_handle_me_t* handle );
4480 \layout Standard
4481
4482 The 
4483 \emph on 
4484 PtlMEAttachAny
4485 \emph default 
4486  function creates a match list consisting of a single entry and attaches
4487  this list to an unused Portal table entry for 
4488 \family typewriter 
4489 interface
4490 \family default 
4491 .
4492 \layout Subsubsection
4493
4494 Return Codes
4495 \layout Description
4496
4497 PTL_OK Indicates success.
4498  
4499 \layout Description
4500
4501 PTL_INV_NI Indicates that 
4502 \family typewriter 
4503 interface
4504 \family default 
4505  is not a valid network interface handle.
4506  
4507 \layout Description
4508
4509 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
4510  
4511 \layout Description
4512
4513 PTL_INV_PROC Indicates that 
4514 \family typewriter 
4515 matchid
4516 \family default 
4517  is not a valid process identifier.
4518  
4519 \layout Description
4520
4521 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
4522  match list entry.
4523  
4524 \layout Description
4525
4526 PTL_PT_FULL Indicates that there are no free entries in the Portal table.
4527 \layout Subsubsection
4528
4529 Arguments
4530 \layout Standard
4531
4532
4533 \begin_inset  Tabular
4534 <lyxtabular version="3" rows="4" columns="3">
4535 <features>
4536 <column alignment="left" valignment="top" width="0.8in">
4537 <column alignment="center" valignment="top" width="0pt">
4538 <column alignment="left" valignment="top" width="4.75in">
4539 <row>
4540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4541 \begin_inset Text
4542
4543 \layout Standard
4544 \noindent 
4545
4546 \family typewriter 
4547 interface
4548 \end_inset 
4549 </cell>
4550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4551 \begin_inset Text
4552
4553 \layout Standard
4554
4555
4556 \series bold 
4557 input
4558 \end_inset 
4559 </cell>
4560 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4561 \begin_inset Text
4562
4563 \layout Standard
4564 \noindent 
4565 A handle for the interface to use.
4566  
4567 \end_inset 
4568 </cell>
4569 </row>
4570 <row>
4571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4572 \begin_inset Text
4573
4574 \layout Standard
4575 \noindent 
4576
4577 \family typewriter 
4578 index
4579 \end_inset 
4580 </cell>
4581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4582 \begin_inset Text
4583
4584 \layout Standard
4585
4586
4587 \series bold 
4588 output
4589 \end_inset 
4590 </cell>
4591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4592 \begin_inset Text
4593
4594 \layout Standard
4595 \noindent 
4596 On successful return, this location will hold the Portal index where the
4597  match list  has been attached.
4598 \end_inset 
4599 </cell>
4600 </row>
4601 <row>
4602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4603 \begin_inset Text
4604
4605 \layout Standard
4606 \noindent 
4607
4608 \family typewriter 
4609 matchid, match_bits, ignorebits, unlink
4610 \end_inset 
4611 </cell>
4612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4613 \begin_inset Text
4614
4615 \layout Standard
4616
4617
4618 \series bold 
4619 input
4620 \end_inset 
4621 </cell>
4622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4623 \begin_inset Text
4624
4625 \layout Standard
4626 \noindent 
4627 See the discussion for 
4628 \shape italic 
4629 PtlMEAttach
4630 \shape default 
4631 .
4632 \end_inset 
4633 </cell>
4634 </row>
4635 <row>
4636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4637 \begin_inset Text
4638
4639 \layout Standard
4640 \noindent 
4641
4642 \family typewriter 
4643 handle
4644 \end_inset 
4645 </cell>
4646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4647 \begin_inset Text
4648
4649 \layout Standard
4650
4651
4652 \series bold 
4653 output
4654 \end_inset 
4655 </cell>
4656 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4657 \begin_inset Text
4658
4659 \layout Standard
4660 \noindent 
4661 On successful return, this location will hold a  handle for the newly created
4662  match list entry.
4663 \end_inset 
4664 </cell>
4665 </row>
4666 </lyxtabular>
4667
4668 \end_inset 
4669
4670
4671 \layout Subsection
4672
4673 PtlMEInsert
4674 \begin_inset LatexCommand \label{sec:meinsert}
4675
4676 \end_inset 
4677
4678
4679 \layout LyX-Code
4680
4681 int PtlMEInsert( ptl_handle_me_t  current,
4682 \newline 
4683                  ptl_process_id_t matchid,
4684 \newline 
4685                  ptl_match_bits_t match_bits,
4686 \newline 
4687                  ptl_match_bits_t ignorebits,
4688 \newline 
4689                  ptl_ins_pos_t    position,
4690 \newline 
4691                  ptl_handle_me_t* handle );
4692 \layout Standard
4693
4694 The 
4695 \emph on 
4696 PtlMEInsert
4697 \emph default 
4698  function creates a new match list entry and inserts this entry into the
4699  match list containing 
4700 \family typewriter 
4701 current
4702 \family default 
4703 .
4704 \layout Subsubsection
4705
4706 Return Codes
4707 \layout Description
4708
4709 PTL_OK Indicates success.
4710  
4711 \layout Description
4712
4713 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
4714  
4715 \layout Description
4716
4717 PTL_INV_PROC Indicates that 
4718 \family typewriter 
4719 matchid
4720 \family default 
4721  is not a valid process identifier.
4722  
4723 \layout Description
4724
4725 PTL_INV_ME Indicates that 
4726 \family typewriter 
4727 current
4728 \family default 
4729  is not a valid match entry handle.
4730  
4731 \layout Description
4732
4733 PTL_ML_TOOLONG Indicates that the resulting match list is too long.
4734  The maximum length for a match list is defined by the interface.
4735  
4736 \layout Description
4737
4738 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
4739  match entry.
4740  
4741 \layout Subsubsection
4742
4743 Arguments
4744 \layout Standard
4745
4746
4747 \begin_inset  Tabular
4748 <lyxtabular version="3" rows="4" columns="3">
4749 <features>
4750 <column alignment="left" valignment="top" width="0.8in">
4751 <column alignment="center" valignment="top" width="0pt">
4752 <column alignment="left" valignment="top" width="4.7in">
4753 <row>
4754 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4755 \begin_inset Text
4756
4757 \layout Standard
4758 \noindent 
4759
4760 \family typewriter 
4761 current
4762 \end_inset 
4763 </cell>
4764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4765 \begin_inset Text
4766
4767 \layout Standard
4768
4769
4770 \series bold 
4771 input
4772 \end_inset 
4773 </cell>
4774 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4775 \begin_inset Text
4776
4777 \layout Standard
4778 \noindent 
4779 A handle for a match entry.
4780   The new match entry will be inserted immediately before or immediately
4781  after this match entry.
4782 \end_inset 
4783 </cell>
4784 </row>
4785 <row>
4786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4787 \begin_inset Text
4788
4789 \layout Standard
4790 \noindent 
4791
4792 \family typewriter 
4793 matchid
4794 \family default 
4795
4796 \family typewriter 
4797 match_bits
4798 \family default 
4799
4800 \family typewriter 
4801 ignorebits
4802 \family default 
4803 ,  
4804 \family typewriter 
4805 unlink
4806 \family default 
4807  
4808 \end_inset 
4809 </cell>
4810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4811 \begin_inset Text
4812
4813 \layout Standard
4814
4815
4816 \series bold 
4817 input
4818 \end_inset 
4819 </cell>
4820 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4821 \begin_inset Text
4822
4823 \layout Standard
4824 \noindent 
4825 See the discussion  for 
4826 \emph on 
4827 PtlMEAttach
4828 \emph default 
4829  
4830 \end_inset 
4831 </cell>
4832 </row>
4833 <row>
4834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4835 \begin_inset Text
4836
4837 \layout Standard
4838 \noindent 
4839
4840 \family typewriter 
4841 position
4842 \end_inset 
4843 </cell>
4844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4845 \begin_inset Text
4846
4847 \layout Standard
4848
4849
4850 \series bold 
4851 input
4852 \end_inset 
4853 </cell>
4854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4855 \begin_inset Text
4856
4857 \layout Standard
4858 \noindent 
4859 Indicates whether the new match entry should be inserted before or after
4860  the 
4861 \family typewriter 
4862 current
4863 \family default 
4864  entry.
4865  Allowed constants: 
4866 \family typewriter 
4867 PTL_INS_BEFORE
4868 \family default 
4869
4870 \family typewriter 
4871 PTL_INS_AFTER
4872 \family default 
4873 .
4874 \end_inset 
4875 </cell>
4876 </row>
4877 <row>
4878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4879 \begin_inset Text
4880
4881 \layout Standard
4882 \noindent 
4883
4884 \family typewriter 
4885 handle
4886 \end_inset 
4887 </cell>
4888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4889 \begin_inset Text
4890
4891 \layout Standard
4892
4893
4894 \series bold 
4895 input
4896 \end_inset 
4897 </cell>
4898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4899 \begin_inset Text
4900
4901 \layout Standard
4902 \noindent 
4903 See the discussion for 
4904 \emph on 
4905 PtlMEAttach
4906 \emph default 
4907 .
4908 \end_inset 
4909 </cell>
4910 </row>
4911 </lyxtabular>
4912
4913 \end_inset 
4914
4915
4916 \layout Subsection
4917
4918 PtlMEUnlink
4919 \begin_inset LatexCommand \label{sec:meunlink}
4920
4921 \end_inset 
4922
4923
4924 \layout LyX-Code
4925
4926 int PtlMEUnlink( ptl_handle_me_t entry );
4927 \layout Standard
4928 \noindent 
4929 The 
4930 \emph on 
4931 PtlMEUnlink
4932 \emph default 
4933  function can be used to unlink a match entry from a match list.
4934  This operation also releases any resources associated with the match entry
4935  (including the associated memory descriptor).
4936  It is an error to use the match entry handle after calling 
4937 \emph on 
4938 PtlMEUnlink
4939 \emph default 
4940 .
4941 \layout Subsubsection
4942
4943 Return Codes
4944 \layout Description
4945
4946 PTL_OK Indicates success.
4947  
4948 \layout Description
4949
4950 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
4951  
4952 \layout Description
4953
4954 PTL_INV_ME Indicates that 
4955 \family typewriter 
4956 entry
4957 \family default 
4958  is not a valid match entry handle.
4959  
4960 \layout Subsubsection
4961
4962 Arguments
4963 \layout Standard
4964
4965
4966 \begin_inset  Tabular
4967 <lyxtabular version="3" rows="1" columns="3">
4968 <features>
4969 <column alignment="right" valignment="top" width="0pt">
4970 <column alignment="center" valignment="top" width="0pt">
4971 <column alignment="center" valignment="top" width="0pt">
4972 <row>
4973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4974 \begin_inset Text
4975
4976 \layout Standard
4977
4978
4979 \family typewriter 
4980 entry
4981 \end_inset 
4982 </cell>
4983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4984 \begin_inset Text
4985
4986 \layout Standard
4987
4988
4989 \series bold 
4990 input
4991 \end_inset 
4992 </cell>
4993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4994 \begin_inset Text
4995
4996 \layout Standard
4997
4998 A handle for the match entry to be unlinked.
4999 \end_inset 
5000 </cell>
5001 </row>
5002 </lyxtabular>
5003
5004 \end_inset 
5005
5006
5007 \layout Section
5008
5009 Memory Descriptors
5010 \begin_inset LatexCommand \label{sec:md}
5011
5012 \end_inset 
5013
5014
5015 \layout Standard
5016
5017 A memory descriptor contains information about a region of an application
5018  process' memory and an event queue where information about the operations
5019  performed on the memory descriptor are recorded.
5020  The Portals API provides two operations to create memory descriptors: 
5021 \emph on 
5022 PtlMDAttach
5023 \emph default 
5024 , and 
5025 \emph on 
5026 PtlMDBind
5027 \emph default 
5028 ; an operation to update a memory descriptor, 
5029 \emph on 
5030 PtlMDUpdate
5031 \emph default 
5032 ; and an operation to unlink and release the resources associated with a
5033  memory descriptor, 
5034 \emph on 
5035 PtlMDUnlink
5036 \emph default 
5037 .
5038 \layout Subsection
5039
5040 The Memory Descriptor Type
5041 \begin_inset LatexCommand \label{sec:md-type}
5042
5043 \end_inset 
5044
5045
5046 \layout LyX-Code
5047
5048 typedef struct {
5049 \newline 
5050     void*           start;
5051 \newline 
5052     ptl_size_t      length;
5053 \newline 
5054     int             threshold;
5055 \newline 
5056     unsigned int    max_offset;
5057 \newline 
5058     unsigned int    options;
5059 \newline 
5060     void*           user_ptr;
5061 \newline 
5062     ptl_handle_eq_t eventq;
5063 \newline 
5064 } ptl_md_t;
5065 \layout Standard
5066 \noindent 
5067 The 
5068 \family typewriter 
5069 ptl_md_t
5070 \family default 
5071  type defines the application view of a memory descriptor.
5072  Values of this type are used to initialize and update the memory descriptors.
5073 \layout Subsubsection
5074
5075 Members
5076 \layout Description
5077
5078 start,\SpecialChar ~
5079 length Specify the memory region associated with the memory descriptor.
5080  The 
5081 \family typewriter 
5082 start
5083 \family default 
5084  member specifies the starting address for the memory region and the 
5085 \family typewriter 
5086 length
5087 \family default 
5088  member specifies the length of the region.
5089  The 
5090 \family typewriter 
5091 start member
5092 \family default 
5093  can be NULL provided that the 
5094 \family typewriter 
5095 length
5096 \family default 
5097  member is zero.
5098  (Zero length buffers are useful to record events.) There are no alignment
5099  restrictions on the starting address or the length of the region; although,
5100  unaligned messages may be slower (i.e., lower bandwidth and/or longer latency)
5101  on some implementations.
5102  
5103 \layout Description
5104
5105 threshold Specifies the maximum number of operations that can be performed
5106  on the memory descriptor.
5107  An operation is any action that could possibly generate an event (see Section\SpecialChar ~
5108
5109 \begin_inset LatexCommand \ref{sec:ek-type}
5110
5111 \end_inset 
5112
5113  for the different types of events).
5114  In the usual case, the threshold value is decremented for each operation
5115  on the memory descriptor.
5116  When the threshold value is zero, the memory descriptor is 
5117 \emph on 
5118 inactive
5119 \emph default 
5120 , and does not respond to operations.
5121  A memory descriptor can have an initial threshold value of zero to allow
5122  for manipulation of an inactive memory descriptor by the local process.
5123  A threshold value of 
5124 \family typewriter 
5125 PTL_MD_THRESH_INF
5126 \family default 
5127  indicates that there is no bound on the number of operations that may be
5128  applied to a memory descriptor.
5129  Note that local operations (e.g., 
5130 \emph on 
5131 PtlMDUpdate
5132 \emph default 
5133 ) are not applied to the threshold count.
5134  
5135 \layout Description
5136
5137 max_offset Specifies the maximum local offset of a memory descriptor.
5138  When the local offset of a memory descriptor exceeds this maximum, the
5139  memory descriptor becomes 
5140 \shape italic 
5141 inactive
5142 \shape default 
5143  and does not respond to further operations.
5144 \layout Description
5145
5146 options Specifies the behavior of the memory descriptor.
5147  There are five options that can be selected: enable put operations (yes
5148  or no), enable get operations (yes or no), offset management (local or
5149  remote), message truncation (yes or no), and acknowledgement (yes or no).
5150  Values for this argument can be constructed using a bitwise or of the following
5151  values: 
5152 \begin_deeper 
5153 \begin_deeper 
5154 \layout Description
5155
5156 PTL_MD_OP_PUT Specifies that the memory descriptor will respond to 
5157 \emph on 
5158 put
5159 \emph default 
5160  operations.
5161  By default, memory descriptors reject 
5162 \emph on 
5163 put
5164 \emph default 
5165  operations.
5166  
5167 \layout Description
5168
5169 PTL_MD_OP_GET Specifies that the memory descriptor will respond to 
5170 \emph on 
5171 get
5172 \emph default 
5173  operations.
5174  By default, memory descriptors reject 
5175 \emph on 
5176 get
5177 \emph default 
5178  operations.
5179  
5180 \layout Description
5181
5182 PTL_MD_MANAGE_REMOTE Specifies that the offset used in accessing the memory
5183  region is provided by the incoming request.
5184  By default, the offset is maintained locally.
5185  When the offset is maintained locally, the offset is incremented by the
5186  length of the request so that the next operation (put and/or get) will
5187  access the next part of the memory region.
5188 \layout Description
5189
5190 PTL_MD_TRUNCATE Specifies that the length provided in the incoming request
5191  can be reduced to match the memory available in the region.
5192  (The memory available in a memory region is determined by subtracting the
5193  offset from the length of the memory region.) By default, if the length
5194  in the incoming operation is greater than the amount of memory available,
5195  the operation is rejected.
5196  
5197 \layout Description
5198
5199 PTL_MD_ACK_DISABLE Specifies that an acknowledgement should 
5200 \emph on 
5201 not
5202 \emph default 
5203  be sent for incoming 
5204 \emph on 
5205 put
5206 \emph default 
5207  operations, even if requested.
5208  By default, acknowledgements are sent for 
5209 \emph on 
5210 put
5211 \emph default 
5212  operations that request an acknowledgement.
5213  Acknowledgements are never sent for 
5214 \emph on 
5215 get
5216 \emph default 
5217  operations.
5218  The value sent in the reply serves as an implicit acknowledgement.
5219  
5220 \end_deeper 
5221 \layout Standard
5222
5223
5224 \series bold 
5225 Note
5226 \series default 
5227 : It is not considered an error to have a memory descriptor that does not
5228  respond to either 
5229 \emph on 
5230 put
5231 \emph default 
5232  or 
5233 \emph on 
5234 get
5235 \emph default 
5236  operations: Every memory descriptor responds to 
5237 \emph on 
5238 reply
5239 \emph default 
5240  operations.
5241  Nor is it considered an error to have a memory descriptor that responds
5242  to both 
5243 \emph on 
5244 put
5245 \emph default 
5246  and 
5247 \emph on 
5248 get
5249 \emph default 
5250  operations.
5251  
5252 \end_deeper 
5253 \layout Description
5254
5255 user_ptr A user-specified value that is associated with the memory descriptor.
5256  The value does not need to be a pointer, but must fit in the space used
5257  by a pointer.
5258  This value (along with other values) is recorded in events associated with
5259  operations on this memory descriptor.
5260 \begin_inset Foot
5261 collapsed true
5262
5263 \layout Standard
5264
5265 Tying the memory descriptor to a user-defined value can be useful when multiple
5266  memory descriptor share the same event queue or when the memory descriptor
5267  needs to be associated with a data structure maintained by the application.
5268  For example, an MPI implementation can set the 
5269 \family typewriter 
5270 user_ptr
5271 \family default 
5272  argument to the value of an MPI Request.
5273  This direct association allows for processing of memory descriptor's by
5274  the MPI implementation without a table lookup or a search for the appropriate
5275  MPI Request.
5276 \end_inset 
5277
5278
5279 \layout Description
5280
5281 eventq A handle for the event queue used to log the operations performed
5282  on the memory region.
5283  If this argument is 
5284 \family typewriter 
5285 PTl_EQ_NONE
5286 \family default 
5287 , operations performed on this memory descriptor are not logged.
5288  
5289 \layout Subsection
5290
5291 PtlMDAttach
5292 \begin_inset LatexCommand \label{sec:mdattach}
5293
5294 \end_inset 
5295
5296
5297 \layout LyX-Code
5298
5299 int PtlMDAttach( ptl_handle_me_t  match,
5300 \newline 
5301                  ptl_md_t         mem_desc,
5302 \newline 
5303                  ptl_unlink_t     unlink_op,
5304 \newline 
5305                  ptl_unlink_t     unlink_nofit,
5306 \newline 
5307                  ptl_handle_md_t* handle );
5308 \layout Standard
5309 \noindent 
5310 Values of the type 
5311 \family typewriter 
5312 ptl_unlink_t
5313 \family default 
5314  are used to control whether an item is unlinked from a list.
5315  The value 
5316 \family typewriter 
5317 PTL_UNLINK
5318 \family default 
5319  enables unlinking.
5320  The value 
5321 \family typewriter 
5322 PTL_RETAIN
5323 \family default 
5324  disables unlinking.
5325 \layout Standard
5326
5327 The 
5328 \emph on 
5329 PtlMDAttach
5330 \emph default 
5331  operation is used to create a memory descriptor and attach it to a match
5332  list entry.
5333  An error code is returned if this match list entry already has an associated
5334  memory descriptor.
5335 \layout Subsubsection
5336
5337 Return Codes
5338 \layout Description
5339
5340 PTL_OK Indicates success.
5341  
5342 \layout Description
5343
5344 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
5345  
5346 \layout Description
5347
5348 PTL_INUSE Indicates that 
5349 \family typewriter 
5350 match
5351 \family default 
5352  already has a memory descriptor attached.
5353  
5354 \layout Description
5355
5356 PTL_INV_ME Indicates that 
5357 \family typewriter 
5358 match
5359 \family default 
5360  is not a valid match entry handle.
5361  
5362 \layout Description
5363
5364 PTL_ILL_MD Indicates that 
5365 \family typewriter 
5366 mem_desc
5367 \family default 
5368  is not a legal memory descriptor.
5369  This may happen because the memory region defined in 
5370 \family typewriter 
5371 mem_desc
5372 \family default 
5373  is invalid or because the network interface associated with the 
5374 \family typewriter 
5375 eventq
5376 \family default 
5377  in 
5378 \family typewriter 
5379 mem_desc
5380 \family default 
5381  is not the same as the network interface associated with 
5382 \family typewriter 
5383 match
5384 \family default 
5385 .
5386  
5387 \layout Description
5388
5389 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
5390  memory descriptor.
5391  
5392 \layout Subsubsection
5393
5394 Arguments
5395 \layout Standard
5396
5397
5398 \begin_inset  Tabular
5399 <lyxtabular version="3" rows="5" columns="3">
5400 <features>
5401 <column alignment="right" valignment="top" width="0pt">
5402 <column alignment="center" valignment="top" width="0pt">
5403 <column alignment="left" valignment="top" width="4.7in">
5404 <row>
5405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5406 \begin_inset Text
5407
5408 \layout Standard
5409
5410
5411 \family typewriter 
5412 match
5413 \end_inset 
5414 </cell>
5415 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5416 \begin_inset Text
5417
5418 \layout Standard
5419
5420
5421 \series bold 
5422 input
5423 \end_inset 
5424 </cell>
5425 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5426 \begin_inset Text
5427
5428 \layout Standard
5429 \noindent 
5430 A handle for the match entry that the memory descriptor will be associated
5431  with.
5432 \end_inset 
5433 </cell>
5434 </row>
5435 <row>
5436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5437 \begin_inset Text
5438
5439 \layout Standard
5440
5441
5442 \family typewriter 
5443 mem_desc
5444 \end_inset 
5445 </cell>
5446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5447 \begin_inset Text
5448
5449 \layout Standard
5450
5451
5452 \series bold 
5453 input
5454 \end_inset 
5455 </cell>
5456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5457 \begin_inset Text
5458
5459 \layout Standard
5460 \noindent 
5461 Provides initial values for the application visible parts of a memory descriptor.
5462   Other than its use for initialization, there is no linkage between this
5463  structure and the memory descriptor maintained by the API.
5464  
5465 \end_inset 
5466 </cell>
5467 </row>
5468 <row>
5469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5470 \begin_inset Text
5471
5472 \layout Standard
5473
5474
5475 \family typewriter 
5476 unlink_op
5477 \end_inset 
5478 </cell>
5479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5480 \begin_inset Text
5481
5482 \layout Standard
5483
5484
5485 \series bold 
5486 input
5487 \end_inset 
5488 </cell>
5489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5490 \begin_inset Text
5491
5492 \layout Standard
5493 \noindent 
5494 A flag to indicate whether the memory descriptor is  unlinked when it becomes
5495  inactive, either because the operation threshold drops to zero or because
5496  the maximum offset has been exceeded.
5497   (Note, the check for unlinking a memory descriptor only occurs after a
5498  the completion of a successful operation.
5499   If the threshold is set to zero during initialization or  using 
5500 \emph on 
5501 PtlMDUpdate
5502 \emph default 
5503 , the memory descriptor is 
5504 \series bold 
5505 not
5506 \series default 
5507   unlinked.) 
5508 \end_inset 
5509 </cell>
5510 </row>
5511 <row>
5512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5513 \begin_inset Text
5514
5515 \layout Standard
5516
5517
5518 \family typewriter 
5519 unlink_nofit
5520 \end_inset 
5521 </cell>
5522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5523 \begin_inset Text
5524
5525 \layout Standard
5526
5527
5528 \series bold 
5529 input
5530 \end_inset 
5531 </cell>
5532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5533 \begin_inset Text
5534
5535 \layout Standard
5536 \noindent 
5537 A flag to indicate whether the memory descriptor is  unlinked when the space
5538  remaining in the memory descriptor is not sufficient for a matching operation.
5539  If an incoming message arrives arrives at a memory descriptor that does
5540  not have sufficient space and the 
5541 \series bold 
5542 PTL_MD_TRUNCATE
5543 \series default 
5544  operation is not specified, the memory descriptor will be unlinked.
5545 \end_inset 
5546 </cell>
5547 </row>
5548 <row>
5549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5550 \begin_inset Text
5551
5552 \layout Standard
5553
5554
5555 \family typewriter 
5556 handle
5557 \end_inset 
5558 </cell>
5559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5560 \begin_inset Text
5561
5562 \layout Standard
5563
5564
5565 \series bold 
5566 output
5567 \end_inset 
5568 </cell>
5569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5570 \begin_inset Text
5571
5572 \layout Standard
5573 \noindent 
5574 On successful return, this location will hold a handle for the newly created
5575  memory descriptor.
5576   The 
5577 \family typewriter 
5578 handle
5579 \family default 
5580  argument can be NULL, in which case the handle will not be returned.
5581 \end_inset 
5582 </cell>
5583 </row>
5584 </lyxtabular>
5585
5586 \end_inset 
5587
5588
5589 \layout Subsection
5590
5591 PtlMDBind
5592 \begin_inset LatexCommand \label{sec:mdbind}
5593
5594 \end_inset 
5595
5596
5597 \layout LyX-Code
5598
5599 int PtlMDBind( ptl_handle_ni_t  interface,
5600 \newline 
5601                ptl_md_t         mem_desc,
5602 \newline 
5603                ptl_handle_md_t* handle );
5604 \layout Standard
5605 \noindent 
5606 The 
5607 \emph on 
5608 PtlMDBind
5609 \emph default 
5610  operation is used to create a 
5611 \begin_inset Quotes eld
5612 \end_inset 
5613
5614 free floating
5615 \begin_inset Quotes erd
5616 \end_inset 
5617
5618  memory descriptor, i.e., a memory descriptor that is not associated with
5619  a match list entry.
5620 \layout Subsubsection
5621
5622 Return Codes
5623 \layout Description
5624
5625 PTL_OK Indicates success.
5626  
5627 \layout Description
5628
5629 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
5630  
5631 \layout Description
5632
5633 PTL_INV_NI Indicates that 
5634 \family typewriter 
5635 interface
5636 \family default 
5637  is not a valid match entry handle.
5638  
5639 \layout Description
5640
5641 PTL_ILL_MD Indicates that 
5642 \family typewriter 
5643 mem_desc
5644 \family default 
5645  is not a legal memory descriptor.
5646  This may happen because the memory region defined in 
5647 \family typewriter 
5648 mem_desc
5649 \family default 
5650  is invalid or because the network interface associated with the 
5651 \family typewriter 
5652 eventq
5653 \family default 
5654  in 
5655 \family typewriter 
5656 mem_desc
5657 \family default 
5658  is not the same as the network interface, 
5659 \family typewriter 
5660 interface
5661 \family default 
5662 .
5663  
5664 \layout Description
5665
5666 PTL_INV_EQ Indicates that the event queue associated with 
5667 \family typewriter 
5668 mem_desc
5669 \family default 
5670  is not valid.
5671  
5672 \layout Description
5673
5674 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
5675  memory descriptor.
5676  
5677 \layout Description
5678
5679 PTL_SEGV Indicates that 
5680 \family typewriter 
5681 handle
5682 \family default 
5683  is not a legal address.
5684  
5685 \layout Subsubsection
5686
5687 Arguments
5688 \layout Standard
5689
5690
5691 \begin_inset  Tabular
5692 <lyxtabular version="3" rows="3" columns="3">
5693 <features>
5694 <column alignment="right" valignment="top" width="0pt">
5695 <column alignment="center" valignment="top" width="0pt">
5696 <column alignment="left" valignment="top" width="4.7in">
5697 <row>
5698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5699 \begin_inset Text
5700
5701 \layout Standard
5702
5703
5704 \family typewriter 
5705 interface
5706 \end_inset 
5707 </cell>
5708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5709 \begin_inset Text
5710
5711 \layout Standard
5712
5713
5714 \series bold 
5715 input
5716 \end_inset 
5717 </cell>
5718 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5719 \begin_inset Text
5720
5721 \layout Standard
5722 \noindent 
5723 A handle for the network interface with which the memory descriptor will
5724  be associated.
5725 \end_inset 
5726 </cell>
5727 </row>
5728 <row>
5729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5730 \begin_inset Text
5731
5732 \layout Standard
5733
5734
5735 \family typewriter 
5736 mem_desc
5737 \end_inset 
5738 </cell>
5739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5740 \begin_inset Text
5741
5742 \layout Standard
5743
5744
5745 \series bold 
5746 input
5747 \end_inset 
5748 </cell>
5749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5750 \begin_inset Text
5751
5752 \layout Standard
5753 \noindent 
5754 Provides initial values for the application visible parts of a memory descriptor.
5755   Other than its use for initialization, there is no linkage between this
5756  structure and the  memory descriptor maintained by the API.
5757  
5758 \end_inset 
5759 </cell>
5760 </row>
5761 <row>
5762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5763 \begin_inset Text
5764
5765 \layout Standard
5766
5767
5768 \family typewriter 
5769 handle
5770 \end_inset 
5771 </cell>
5772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5773 \begin_inset Text
5774
5775 \layout Standard
5776
5777
5778 \series bold 
5779 output
5780 \end_inset 
5781 </cell>
5782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5783 \begin_inset Text
5784
5785 \layout Standard
5786 \noindent 
5787 On successful return, this location will hold a  handle for the newly created
5788  memory descriptor.
5789   The 
5790 \family typewriter 
5791 handle
5792 \family default 
5793  argument must be a valid address and cannot be NULL.
5794 \end_inset 
5795 </cell>
5796 </row>
5797 </lyxtabular>
5798
5799 \end_inset 
5800
5801
5802 \layout Subsection
5803
5804 PtlMDUnlink
5805 \begin_inset LatexCommand \label{sec:mdfree}
5806
5807 \end_inset 
5808
5809
5810 \layout LyX-Code
5811
5812 int PtlMDUnlink( ptl_handle_md_t mem_desc );
5813 \layout Standard
5814 \noindent 
5815 The 
5816 \emph on 
5817 PtlMDUnlink
5818 \emph default 
5819  function unlinks the memory descriptor from any match list entry it may
5820  be linked to and releases the resources associated with a memory descriptor.
5821  (This function does not free the memory region associated with the memory
5822  descriptor.) This function also releases the resources associated with a
5823  floating memory descriptor.
5824  Only memory descriptors with no pending operations may be unlinked.
5825 \layout Subsubsection
5826
5827 Return Codes
5828 \layout Description
5829
5830 PTL_OK Indicates success.
5831  
5832 \layout Description
5833
5834 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
5835  
5836 \layout Description
5837
5838 PTL_INV_MD Indicates that 
5839 \family typewriter 
5840 mem_desc
5841 \family default 
5842  is not a valid memory descriptor handle.
5843 \layout Description
5844
5845 PTL_MD_INUSE Indicates that 
5846 \family typewriter 
5847 mem_desc
5848 \family default 
5849  has pending operations and cannot be unlinked.
5850 \layout Subsubsection
5851
5852 Arguments
5853 \layout Standard
5854
5855
5856 \begin_inset  Tabular
5857 <lyxtabular version="3" rows="1" columns="3">
5858 <features>
5859 <column alignment="right" valignment="top" width="0pt">
5860 <column alignment="center" valignment="top" width="0pt">
5861 <column alignment="left" valignment="top" width="4.7in">
5862 <row>
5863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5864 \begin_inset Text
5865
5866 \layout Standard
5867
5868
5869 \family typewriter 
5870 mem_desc
5871 \end_inset 
5872 </cell>
5873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5874 \begin_inset Text
5875
5876 \layout Standard
5877
5878
5879 \series bold 
5880 input
5881 \end_inset 
5882 </cell>
5883 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5884 \begin_inset Text
5885
5886 \layout Standard
5887 \noindent 
5888 A handle for the memory descriptor to be released.
5889 \end_inset 
5890 </cell>
5891 </row>
5892 </lyxtabular>
5893
5894 \end_inset 
5895
5896
5897 \layout Subsection
5898
5899 PtlMDUpdate
5900 \begin_inset LatexCommand \label{sec:mdupdate}
5901
5902 \end_inset 
5903
5904
5905 \layout LyX-Code
5906
5907 int PtlMDUpdate( ptl_handle_md_t mem_desc,
5908 \newline 
5909                  ptl_md_t*       old_md,
5910 \newline 
5911                  ptl_md_t*       new_md,
5912 \newline 
5913                  ptl_handle_eq_t testq );
5914 \layout Standard
5915 \noindent 
5916 The 
5917 \emph on 
5918 PtlMDUpdate
5919 \emph default 
5920  function provides a conditional, atomic update operation for memory descriptors.
5921  The memory descriptor identified by 
5922 \family typewriter 
5923 mem_desc
5924 \family default 
5925  is only updated if the event queue identified by 
5926 \family typewriter 
5927 testq
5928 \family default 
5929  is empty.
5930  The intent is to only enable updates to the memory descriptor when no new
5931  messages have arrived since the last time the queue was checked.
5932  See section\SpecialChar ~
5933
5934 \begin_inset LatexCommand \ref{sec:exmpi}
5935
5936 \end_inset 
5937
5938  for an example of how this function can be used.
5939 \layout Standard
5940
5941 If 
5942 \family typewriter 
5943 new
5944 \family default 
5945  is not NULL the memory descriptor identified by handle will be updated
5946  to reflect the values in the structure pointed to by 
5947 \family typewriter 
5948 new
5949 \family default 
5950  if 
5951 \family typewriter 
5952 testq
5953 \family default 
5954  has the value 
5955 \family typewriter 
5956 PTL_EQ_NONE
5957 \family default 
5958  or if the event queue identified by 
5959 \family typewriter 
5960 testq
5961 \family default 
5962  is empty.
5963  If 
5964 \family typewriter 
5965 old
5966 \family default 
5967  is not NULL, the current value of the memory descriptor identified by 
5968 \family typewriter 
5969 mem_desc
5970 \family default 
5971  is recorded in the location identified by 
5972 \family typewriter 
5973 old
5974 \family default 
5975 .
5976 \layout Subsubsection
5977
5978 Return Codes
5979 \layout Description
5980
5981 PTL_OK Indicates success.
5982  
5983 \layout Description
5984
5985 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
5986  
5987 \layout Description
5988
5989 PTL_NOUPDATE Indicates that the update was not performed because 
5990 \family typewriter 
5991 testq
5992 \family default 
5993  was not empty.
5994  
5995 \layout Description
5996
5997 PTL_INV_MD Indicates that 
5998 \family typewriter 
5999 mem_desc
6000 \family default 
6001  is not a valid memory descriptor handle.
6002  
6003 \layout Description
6004
6005 PTL_ILL_MD Indicates that the value pointed to by 
6006 \family typewriter 
6007 new
6008 \family default 
6009  is not a legal memory descriptor (e.g., the memory region specified by the
6010  memory descriptor may be invalid).
6011  
6012 \layout Description
6013
6014 PTL_INV_EQ Indicates that 
6015 \family typewriter 
6016 testq
6017 \family default 
6018  is not a valid event queue handle.
6019  
6020 \layout Description
6021
6022 PTL_SEGV Indicates that 
6023 \family typewriter 
6024 new
6025 \family default 
6026  or 
6027 \family typewriter 
6028 old
6029 \family default 
6030  is not a legal address.
6031  
6032 \layout Subsubsection
6033
6034 Arguments
6035 \layout Standard
6036
6037
6038 \begin_inset  Tabular
6039 <lyxtabular version="3" rows="4" columns="3">
6040 <features>
6041 <column alignment="right" valignment="top" width="0pt">
6042 <column alignment="center" valignment="top" width="0pt">
6043 <column alignment="left" valignment="top" width="4.7in">
6044 <row>
6045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6046 \begin_inset Text
6047
6048 \layout Standard
6049
6050
6051 \family typewriter 
6052 mem_desc
6053 \end_inset 
6054 </cell>
6055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6056 \begin_inset Text
6057
6058 \layout Standard
6059
6060
6061 \series bold 
6062 input
6063 \end_inset 
6064 </cell>
6065 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6066 \begin_inset Text
6067
6068 \layout Standard
6069 \noindent 
6070 A handle for the memory descriptor to update.
6071 \end_inset 
6072 </cell>
6073 </row>
6074 <row>
6075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6076 \begin_inset Text
6077
6078 \layout Standard
6079
6080
6081 \family typewriter 
6082 old_md
6083 \end_inset 
6084 </cell>
6085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6086 \begin_inset Text
6087
6088 \layout Standard
6089
6090
6091 \series bold 
6092 output
6093 \end_inset 
6094 </cell>
6095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6096 \begin_inset Text
6097
6098 \layout Standard
6099 \noindent 
6100 If 
6101 \family typewriter 
6102 old_md
6103 \family default 
6104  is not the value 
6105 \family typewriter 
6106 NULL
6107 \family default 
6108 , the current value of the memory descriptor will be stored in the location
6109  identified by 
6110 \family typewriter 
6111 old
6112 \family default 
6113 _md.
6114 \end_inset 
6115 </cell>
6116 </row>
6117 <row>
6118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6119 \begin_inset Text
6120
6121 \layout Standard
6122
6123
6124 \family typewriter 
6125 new_md
6126 \end_inset 
6127 </cell>
6128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6129 \begin_inset Text
6130
6131 \layout Standard
6132
6133
6134 \series bold 
6135 input
6136 \end_inset 
6137 </cell>
6138 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6139 \begin_inset Text
6140
6141 \layout Standard
6142 \noindent 
6143 If 
6144 \family typewriter 
6145 new_md
6146 \family default 
6147  is not the value 
6148 \family typewriter 
6149 NULL
6150 \family default 
6151 , this argument provides the new values for the memory descriptor, if the
6152  update is performed.
6153 \end_inset 
6154 </cell>
6155 </row>
6156 <row>
6157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6158 \begin_inset Text
6159
6160 \layout Standard
6161
6162
6163 \family typewriter 
6164 testq
6165 \end_inset 
6166 </cell>
6167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6168 \begin_inset Text
6169
6170 \layout Standard
6171
6172
6173 \series bold 
6174 input
6175 \end_inset 
6176 </cell>
6177 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6178 \begin_inset Text
6179
6180 \layout Standard
6181 \noindent 
6182 A handle for an event queue used to predicate the update.
6183  If 
6184 \family typewriter 
6185 testq
6186 \family default 
6187  is equal to 
6188 \family typewriter 
6189 PTL_EQ_NONE
6190 \family default 
6191 , the update is performed unconditionally.
6192   Otherwise, the update is performed if and only if 
6193 \family typewriter 
6194 testq
6195 \family default 
6196  is empty.
6197   If the update is  not performed, the function returns the value 
6198 \family typewriter 
6199 PTL_NOUPDATE
6200 \family default 
6201 .
6202   (Note, the 
6203 \family typewriter 
6204 testq
6205 \family default 
6206  argument does not need to be the same as  the event queue associated with
6207  the memory descriptor.)
6208 \end_inset 
6209 </cell>
6210 </row>
6211 </lyxtabular>
6212
6213 \end_inset 
6214
6215
6216 \layout Standard
6217
6218 The conditional update can be used to ensure that the memory descriptor
6219  has not changed between the time it was examined and the time it is updated.
6220  In particular, it is needed to support an MPI implementation where the
6221  activity of searching an unexpected message queue and posting a receive
6222  must be atomic.
6223 \layout Section
6224
6225 Events and Event Queues
6226 \begin_inset LatexCommand \label{sec:eq}
6227
6228 \end_inset 
6229
6230
6231 \layout Standard
6232
6233 Event queues are used to log operations performed on memory descriptors.
6234  They can also be used to hold acknowledgements for completed 
6235 \emph on 
6236 put
6237 \emph default 
6238  operations and to note when the data specified in a 
6239 \emph on 
6240 put
6241 \emph default 
6242  operation has been sent (i.e., when it is safe to reuse the buffer that holds
6243  this data).
6244  Multiple memory descriptors can share a single event queue.
6245 \layout Standard
6246
6247 In addition to the 
6248 \family typewriter 
6249 ptl_handle_eq_t
6250 \family default 
6251  type, the Portals API defines two types associated with events: The 
6252 \family typewriter 
6253
6254 \newline 
6255 ptl_event_kind_t
6256 \family default 
6257  type defines the kinds of events that can be stored in an event queue.
6258  The 
6259 \family typewriter 
6260 ptl_event_t
6261 \family default 
6262  type defines a structure that holds the information associated with an
6263  event.
6264 \layout Standard
6265
6266 The Portals API also provides four functions for dealing with event queues:
6267  The 
6268 \emph on 
6269 PtlEQAlloc
6270 \emph default 
6271  function is used to allocate the API resources needed for an event queue,
6272  the 
6273 \emph on 
6274 PtlEQFree
6275 \emph default 
6276  function is used to release these resources, the 
6277 \emph on 
6278 PtlEQGet
6279 \emph default 
6280  function can be used to get the next event from an event queue, and the
6281  
6282 \emph on 
6283 PtlEQWait
6284 \emph default 
6285  function can be used to block a process (or thread) until an event queue
6286  has at least one event.
6287 \layout Subsection
6288
6289 Kinds of Events
6290 \begin_inset LatexCommand \label{sec:ek-type}
6291
6292 \end_inset 
6293
6294
6295 \layout LyX-Code
6296
6297 typedef enum { 
6298 \newline 
6299     PTL_EVENT_GET_START, PTL_EVENT_GET_END, PTL_EVENT_GET_FAIL,
6300 \newline 
6301     PTL_EVENT_PUT_START, PTL_EVENT_PUT_END, PTL_EVENT_PUT_FAIL,
6302 \newline 
6303     PTL_EVENT_REPLY_START, PTL_EVENT_REPLY_END, PTL_EVENT_REPLY_FAIL,
6304 \newline 
6305     PTL_EVENT_SEND_START, PTL_EVENT_SEND_END, PTL_EVENT_SEND_FAIL,
6306 \newline 
6307     PTL_EVENT_ACK,
6308 \newline 
6309     PTL_EVENT_UNLINK
6310 \newline 
6311 } ptl_event_kind_t;
6312 \layout Standard
6313 \noindent 
6314 The Portals API defines fourteen types of events that can be logged in an
6315  event queue: 
6316 \layout Description
6317
6318 PTL_EVENT_GET_START A remote 
6319 \emph on 
6320 get
6321 \emph default 
6322  operation has been started on the memory descriptor.
6323  The memory region associated with this descriptor should not be altered
6324  until the corresponding END or FAIL event is logged.
6325 \layout Description
6326
6327 PTL_EVENT_GET_END A previously initiated 
6328 \emph on 
6329 get
6330 \emph default 
6331  operation completed successfully.
6332  This event is logged after the reply has been sent by the local node.
6333  As such, the process could free the memory descriptor once it sees this
6334  event.
6335  
6336 \layout Description
6337
6338 PTL_EVENT_GET_FAIL A previously initiated 
6339 \emph on 
6340 get
6341 \emph default 
6342  operation completed unsuccessfully.
6343  This event is logged after the reply has been sent by the local node.
6344  As such, the process could free the memory descriptor once it sees this
6345  event.
6346  
6347 \layout Description
6348
6349 PTL_EVENT_PUT_START A remote 
6350 \emph on 
6351 put
6352 \emph default 
6353  operation has been started on the memory descriptor.
6354  The memory region associated with this descriptor should should be considered
6355  volatile until the corresponding END or FAIL event is logged.
6356 \layout Description
6357
6358 PTL_EVENT_PUT_END A previously initiated 
6359 \emph on 
6360 put
6361 \emph default 
6362  operation completed successfully.
6363  The underlying layers will not alter the memory (on behalf of this operation)
6364  once this event has been logged.
6365  
6366 \layout Description
6367
6368 PTL_EVENT_PUT_FAIL A previously initiated 
6369 \emph on 
6370 put
6371 \emph default 
6372  operation completed unsuccessfully.
6373  The underlying layers will not alter the memory (on behalf of this operation)
6374  once this event has been logged.
6375  
6376 \layout Description
6377
6378 PTL_EVENT_REPLY_START A 
6379 \emph on 
6380 reply
6381 \emph default 
6382  operation has been started on the memory descriptor.
6383  
6384 \layout Description
6385
6386 PTL_EVENT_REPLY_END A previously initiated 
6387 \emph on 
6388 reply
6389 \emph default 
6390  operation has completed successfully .
6391  This event is logged after the data (if any) from the reply has been written
6392  into the memory descriptor.
6393  
6394 \layout Description
6395
6396 PTL_EVENT_REPLY_FAIL A previously initiated 
6397 \emph on 
6398 reply
6399 \emph default 
6400  operation has completed unsuccessfully.
6401  This event is logged after the data (if any) from the reply has been written
6402  into the memory descriptor.
6403  
6404 \layout Description
6405
6406 PTL_EVENT_ACK An 
6407 \emph on 
6408 acknowledgement
6409 \emph default 
6410  was received.
6411  This event is logged when the acknowledgement is received 
6412 \layout Description
6413
6414 PTL_EVENT_SEND_START An outgoing 
6415 \emph on 
6416 send
6417 \emph default 
6418  operation has been started.
6419  The memory region associated with this descriptor should not be altered
6420  until the corresponding END or FAIL event is logged.
6421 \layout Description
6422
6423 PTL_EVENT_SEND_END A previously initiated 
6424 \emph on 
6425 send
6426 \emph default 
6427  operation has completed successfully.
6428  This event is logged after the entire buffer has been sent and it is safe
6429  for the application to reuse the buffer.
6430  
6431 \layout Description
6432
6433 PTL_EVENT_SEND_FAIL A previously initiated 
6434 \emph on 
6435 send
6436 \emph default 
6437  operation has completed unsuccessfully.
6438  The process can safely manipulate the memory or free the memory descriptor
6439  once it sees this event.
6440 \layout Description
6441
6442 PTL_EVENT_UNLINK A memory descriptor associated with this event queue has
6443  been automatically unlinked.
6444  This event is not generated when a memory descriptor is explicitly unlinked
6445  by calling 
6446 \shape italic 
6447 PtlMDUnlink
6448 \shape default 
6449 .
6450  This event does not decrement the threshold count.
6451 \layout Subsection
6452
6453 Event Ordering
6454 \layout Standard
6455
6456 The Portals API guarantees that a when a process initiates two operations
6457  on a remote process, the operations will be initiated on the remote process
6458  in the same order that they were initiated on the original process.
6459  As an example, if process A intitates two 
6460 \emph on 
6461 put
6462 \emph default 
6463  operations, 
6464 \emph on 
6465 x
6466 \emph default 
6467  and 
6468 \emph on 
6469 y
6470 \emph default 
6471 , on process B, the Portals API guarantees that process A will receive the
6472  
6473 \family typewriter 
6474 PTL_EVENT_SEND_START
6475 \family default 
6476  events for 
6477 \emph on 
6478 x
6479 \emph default 
6480  and 
6481 \emph on 
6482 y
6483 \emph default 
6484  in the same order that process B receives the 
6485 \family typewriter 
6486 PTL_EVENT_PUT_START
6487 \family default 
6488  events for 
6489 \emph on 
6490 x
6491 \emph default 
6492  and 
6493 \emph on 
6494 y
6495 \emph default 
6496 .
6497  Notice that the API does not guarantee that the start events will be delivered
6498  in the same order that process A initiated the 
6499 \emph on 
6500 x
6501 \emph default 
6502  and 
6503 \emph on 
6504 y
6505 \emph default 
6506  operations.
6507  If process A needs to ensure the ordering of these operations, it should
6508  include code to wait for the initiation of 
6509 \emph on 
6510 x
6511 \emph default 
6512  before it initiates 
6513 \emph on 
6514 y
6515 \emph default 
6516 .
6517 \layout Subsection
6518
6519 Failure Notification
6520 \layout Standard
6521
6522 Operations may fail to complete successfully; however, unless the node itself
6523  fails, every operation that is started will eventually complete.
6524  While an operation is in progress, the memory associated with the operation
6525  should not be viewed (in the case of a put or a reply) or altered (in the
6526  case of a send or get).
6527  Operation completion, whether successful or unsuccessful, is final.
6528  That is, when an operation completes, the memory associated with the operation
6529  will no longer be read or altered by the operation.
6530  A network interface can use the 
6531 \family typewriter 
6532 ptl_ni_fail_t
6533 \family default 
6534  to define more specific information regarding the failure of the operation
6535  and record this information in the 
6536 \family typewriter 
6537 ni_fail_type
6538 \family default 
6539  field of the event.
6540 \layout Subsection
6541
6542 The Event Type
6543 \begin_inset LatexCommand \label{sec:event-type}
6544
6545 \end_inset 
6546
6547
6548 \layout LyX-Code
6549
6550 typedef struct {
6551 \newline 
6552     ptl_event_kind_t      type;
6553 \newline 
6554     ptl_process_id_t      initiator;
6555 \newline 
6556     ptl_uid_t             uid;
6557 \layout LyX-Code
6558
6559     ptl_pt_index_t        portal;
6560 \newline 
6561     ptl_match_bits_t      match_bits;
6562 \newline 
6563     ptl_size_t            rlength;
6564 \newline 
6565     ptl_size_t            mlength;
6566 \newline 
6567     ptl_size_t            offset; 
6568 \newline 
6569     ptl_handle_md_t       md_handle;
6570 \newline 
6571     ptl_md_t              mem_desc;
6572 \newline 
6573     ptl_hdr_data_t        hdr_data;
6574 \newline 
6575     ptl_seq_t             link;
6576 \newline 
6577     ptl_ni_fail_t         ni_fail_type;
6578 \newline 
6579     volatile ptl_seq_t    sequence;
6580 \newline 
6581 } ptl_event_t;
6582 \layout Standard
6583 \noindent 
6584 An event structure includes the following members: 
6585 \layout Description
6586
6587 type Indicates the type of the event.
6588  
6589 \layout Description
6590
6591 initiator The id of the initiator.
6592  
6593 \layout Description
6594
6595 portal The Portal table index specified in the request.
6596  
6597 \layout Description
6598
6599 match_bits A copy of the match bits specified in the request.
6600  See section\SpecialChar ~
6601
6602 \begin_inset LatexCommand \ref{sec:me}
6603
6604 \end_inset 
6605
6606  for more information on match bits.
6607  
6608 \layout Description
6609
6610 rlength The length (in bytes) specified in the request.
6611  
6612 \layout Description
6613
6614 mlength The length (in bytes) of the data that was manipulated by the operation.
6615  For truncated operations, the manipulated length will be the number of
6616  bytes specified by the memory descriptor (possibly with an offset) operation.
6617  For all other operations, the manipulated length will be the length of
6618  the requested operation.
6619  
6620 \layout Description
6621
6622 offset Is the displacement (in bytes) into the memory region that the operation
6623  used.
6624  The offset can be determined by the operation (see Section\SpecialChar ~
6625
6626 \begin_inset LatexCommand \ref{sec:datamovement}
6627
6628 \end_inset 
6629
6630 ) for a remote managed memory descriptor, or by the local memory descriptor
6631  (see Section\SpecialChar ~
6632
6633 \begin_inset LatexCommand \ref{sec:md}
6634
6635 \end_inset 
6636
6637 ).
6638  
6639 \layout Description
6640
6641 md_handle Is the handle to the memory descriptor associated with the event.
6642 \layout Description
6643
6644 mem_desc Is the state of the memory descriptor immediately after the event
6645  has been processed.
6646  
6647 \layout Description
6648
6649 hdr_data 64 bits of out-of-band user data (see Section\SpecialChar ~
6650
6651 \begin_inset LatexCommand \ref{sec:put}
6652
6653 \end_inset 
6654
6655 ).
6656  
6657 \layout Description
6658
6659 link The 
6660 \emph on 
6661 link
6662 \emph default 
6663  member is used to link 
6664 \family typewriter 
6665 START
6666 \family default 
6667  events with the 
6668 \family typewriter 
6669 END
6670 \family default 
6671  or 
6672 \family typewriter 
6673 FAIL
6674 \family default 
6675  event that signifies completion of the operation.
6676  The 
6677 \emph on 
6678 link
6679 \emph default 
6680  member will be the same for the two events associated with an operation.
6681  The link member is also used to link an 
6682 \family typewriter 
6683 UNLINK
6684 \family default 
6685  event with the event that caused the memory descriptor to be unlinked.
6686 \layout Description
6687
6688 sequence The sequence number for this event.
6689  Sequence numbers are unique to each event.
6690 \layout Comment
6691
6692 The 
6693 \emph on 
6694 sequence
6695 \emph default 
6696  member is the last member and is volatile to support SMP implementations.
6697  When an event structure is filled in, the 
6698 \emph on 
6699 sequence
6700 \emph default 
6701  member should be written after all other members have been updated.
6702  Moreover, a memory barrier should be inserted between the updating of other
6703  members and the updating of the 
6704 \emph on 
6705 sequence
6706 \emph default 
6707  member.
6708 \layout Subsection
6709
6710 PtlEQAlloc
6711 \begin_inset LatexCommand \label{sec:eqalloc}
6712
6713 \end_inset 
6714
6715
6716 \layout LyX-Code
6717
6718 int PtlEQAlloc( ptl_handle_ni_t  interface,
6719 \newline 
6720                 ptl_size_t       count,
6721 \newline 
6722                 ptl_handle_eq_t* handle );
6723 \layout Standard
6724 \noindent 
6725 The 
6726 \emph on 
6727 PtlEQAlloc
6728 \emph default 
6729  function is used to build an event queue.
6730  
6731 \layout Subsubsection
6732
6733 Return Codes
6734 \layout Description
6735
6736 PTL_OK Indicates success.
6737  
6738 \layout Description
6739
6740 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
6741  
6742 \layout Description
6743
6744 PTL_INV_NI Indicates that 
6745 \family typewriter 
6746 interface
6747 \family default 
6748  is not a valid network interface handle.
6749  
6750 \layout Description
6751
6752 PTL_NOSPACE Indicates that there is insufficient memory to allocate the
6753  event queue.
6754  
6755 \layout Description
6756
6757 PTL_SEGV Indicates that 
6758 \family typewriter 
6759 handle
6760 \family default 
6761  is not a legal address.
6762  
6763 \layout Subsubsection
6764
6765 Arguments
6766 \layout Standard
6767
6768
6769 \begin_inset  Tabular
6770 <lyxtabular version="3" rows="3" columns="3">
6771 <features>
6772 <column alignment="right" valignment="top" width="0pt">
6773 <column alignment="center" valignment="top" width="0pt">
6774 <column alignment="left" valignment="top" width="4.7in">
6775 <row>
6776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6777 \begin_inset Text
6778
6779 \layout Standard
6780
6781
6782 \family typewriter 
6783 interface
6784 \end_inset 
6785 </cell>
6786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6787 \begin_inset Text
6788
6789 \layout Standard
6790
6791
6792 \series bold 
6793 input
6794 \end_inset 
6795 </cell>
6796 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6797 \begin_inset Text
6798
6799 \layout Standard
6800 \noindent 
6801 A handle for the interface with which the event queue  will be associated.
6802 \end_inset 
6803 </cell>
6804 </row>
6805 <row>
6806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6807 \begin_inset Text
6808
6809 \layout Standard
6810
6811
6812 \family typewriter 
6813 count
6814 \end_inset 
6815 </cell>
6816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6817 \begin_inset Text
6818
6819 \layout Standard
6820
6821
6822 \series bold 
6823 input
6824 \end_inset 
6825 </cell>
6826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6827 \begin_inset Text
6828
6829 \layout Standard
6830 \noindent 
6831 The number of events that can be stored in the event queue.
6832 \end_inset 
6833 </cell>
6834 </row>
6835 <row>
6836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6837 \begin_inset Text
6838
6839 \layout Standard
6840
6841
6842 \family typewriter 
6843 handle
6844 \end_inset 
6845 </cell>
6846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6847 \begin_inset Text
6848
6849 \layout Standard
6850
6851
6852 \series bold 
6853 output
6854 \end_inset 
6855 </cell>
6856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6857 \begin_inset Text
6858
6859 \layout Standard
6860 \noindent 
6861 On successful return, this location will hold a handle for the newly created
6862  event queue.
6863 \end_inset 
6864 </cell>
6865 </row>
6866 </lyxtabular>
6867
6868 \end_inset 
6869
6870
6871 \layout Subsection
6872
6873 PtlEQFree
6874 \begin_inset LatexCommand \label{sec:eqfree}
6875
6876 \end_inset 
6877
6878
6879 \layout LyX-Code
6880
6881 int PtlEQFree( ptl_handle_eq_t eventq );
6882 \layout Standard
6883 \noindent 
6884 The 
6885 \emph on 
6886 PtlEQFree
6887 \emph default 
6888  function releases the resources associated with an event queue.
6889  It is up to the user to insure that no memory descriptors are associated
6890  with the event queue once it is freed.
6891  
6892 \layout Subsubsection
6893
6894 Return Codes
6895 \layout Description
6896
6897 PTL_OK Indicates success.
6898  
6899 \layout Description
6900
6901 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
6902  
6903 \layout Description
6904
6905 PTL_INV_EQ Indicates that 
6906 \family typewriter 
6907 eventq
6908 \family default 
6909  is not a valid event queue handle.
6910  
6911 \layout Subsubsection
6912
6913 Arguments
6914 \layout Standard
6915
6916
6917 \begin_inset  Tabular
6918 <lyxtabular version="3" rows="1" columns="3">
6919 <features>
6920 <column alignment="right" valignment="top" width="0pt">
6921 <column alignment="center" valignment="top" width="0pt">
6922 <column alignment="left" valignment="top" width="4.7in">
6923 <row>
6924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6925 \begin_inset Text
6926
6927 \layout Standard
6928
6929
6930 \family typewriter 
6931 eventq
6932 \end_inset 
6933 </cell>
6934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6935 \begin_inset Text
6936
6937 \layout Standard
6938
6939
6940 \series bold 
6941 input
6942 \end_inset 
6943 </cell>
6944 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
6945 \begin_inset Text
6946
6947 \layout Standard
6948
6949 A handle for the event queue to be released.
6950 \end_inset 
6951 </cell>
6952 </row>
6953 </lyxtabular>
6954
6955 \end_inset 
6956
6957
6958 \layout Subsection
6959
6960 PtlEQGet
6961 \begin_inset LatexCommand \label{sec:eqget}
6962
6963 \end_inset 
6964
6965
6966 \layout LyX-Code
6967
6968 int PtlEQGet( ptl_handle_eq_t eventq,
6969 \newline 
6970               ptl_event_t*    event );
6971 \layout Standard
6972 \noindent 
6973 The 
6974 \emph on 
6975 PTLEQGet
6976 \emph default 
6977  function is a nonblocking function that can be used to get the next event
6978  in an event queue.
6979  The event is removed from the queue.
6980 \layout Subsubsection
6981
6982 Return Codes
6983 \layout Description
6984
6985 PTL_OK Indicates success.
6986  
6987 \layout Description
6988
6989 PTL_EQ_DROPPED Indicates success (i.e., an event is returned) and that at
6990  least one event between this event and the last event obtained (using 
6991 \emph on 
6992 PtlEQGet
6993 \emph default 
6994  or 
6995 \emph on 
6996 PtlEQWait
6997 \emph default 
6998 ) from this event queue has been dropped due to limited space in the event
6999  queue.
7000  
7001 \layout Description
7002
7003 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
7004  
7005 \layout Description
7006
7007 PTL_EQ_EMPTY Indicates that 
7008 \family typewriter 
7009 eventq
7010 \family default 
7011  is empty or another thread is waiting on 
7012 \emph on 
7013 PtlEQWait
7014 \emph default 
7015 .
7016  
7017 \layout Description
7018
7019 PTL_INV_EQ Indicates that 
7020 \family typewriter 
7021 eventq
7022 \family default 
7023  is not a valid event queue handle.
7024  
7025 \layout Description
7026
7027 PTL_SEGV Indicates that 
7028 \family typewriter 
7029 event
7030 \family default 
7031  is not a legal address.
7032  
7033 \layout Subsubsection
7034
7035 Arguments
7036 \layout Standard
7037
7038
7039 \begin_inset  Tabular
7040 <lyxtabular version="3" rows="2" columns="3">
7041 <features>
7042 <column alignment="right" valignment="top" width="0pt">
7043 <column alignment="center" valignment="top" width="0pt">
7044 <column alignment="left" valignment="top" width="4.5in">
7045 <row>
7046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7047 \begin_inset Text
7048
7049 \layout Standard
7050
7051
7052 \family typewriter 
7053 eventq
7054 \end_inset 
7055 </cell>
7056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7057 \begin_inset Text
7058
7059 \layout Standard
7060
7061
7062 \series bold 
7063 input
7064 \end_inset 
7065 </cell>
7066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7067 \begin_inset Text
7068
7069 \layout Standard
7070 \noindent 
7071 A handle for the event queue.
7072 \end_inset 
7073 </cell>
7074 </row>
7075 <row>
7076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7077 \begin_inset Text
7078
7079 \layout Standard
7080
7081
7082 \family typewriter 
7083 event
7084 \end_inset 
7085 </cell>
7086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7087 \begin_inset Text
7088
7089 \layout Standard
7090
7091
7092 \series bold 
7093 output
7094 \end_inset 
7095 </cell>
7096 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7097 \begin_inset Text
7098
7099 \layout Standard
7100 \noindent 
7101 On successful return, this location will hold the  values associated with
7102  the next event in the event queue.
7103 \end_inset 
7104 </cell>
7105 </row>
7106 </lyxtabular>
7107
7108 \end_inset 
7109
7110
7111 \layout Subsection
7112
7113 PtlEQWait
7114 \begin_inset LatexCommand \label{sec:eqwait}
7115
7116 \end_inset 
7117
7118
7119 \layout LyX-Code
7120
7121 int PtlEQWait( ptl_handle_eq_t eventq,
7122 \newline 
7123                ptl_event_t*    event );
7124 \layout Standard
7125 \noindent 
7126 The 
7127 \emph on 
7128 PTLEQWait
7129 \emph default 
7130  function can be used to block the calling process (thread) until there
7131  is an event in an event queue.
7132  This function also returns the next event in the event queue and removes
7133  this event from the queue.
7134  This is the only blocking operation in the Portals 3.2 API.
7135  In the event that multiple threads are waiting on the same event queue,
7136  PtlEQWait is guaranteed to wake exactly one thread, but the order in which
7137  they are awakened is not specified.
7138 \layout Subsubsection
7139
7140 Return Codes
7141 \layout Description
7142
7143 PTL_OK Indicates success.
7144  
7145 \layout Description
7146
7147 PTL_EQ_DROPPED Indicates success (i.e., an event is returned) and that at
7148  least one event between this event and the last event obtained (using 
7149 \emph on 
7150 PtlEQGet
7151 \emph default 
7152  or 
7153 \emph on 
7154 PtlEQWait
7155 \emph default 
7156 ) from this event queue has been dropped due to limited space in the event
7157  queue.
7158  
7159 \layout Description
7160
7161 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
7162  
7163 \layout Description
7164
7165 PTL_INV_EQ Indicates that 
7166 \family typewriter 
7167 eventq
7168 \family default 
7169  is not a valid event queue handle.
7170  
7171 \layout Description
7172
7173 PTL_SEGV Indicates that 
7174 \family typewriter 
7175 event
7176 \family default 
7177  is not a legal address.
7178  queue handle.
7179  
7180 \layout Subsubsection
7181
7182 Arguments
7183 \layout Standard
7184 \noindent 
7185
7186 \begin_inset  Tabular
7187 <lyxtabular version="3" rows="2" columns="3">
7188 <features>
7189 <column alignment="right" valignment="top" width="0pt">
7190 <column alignment="center" valignment="top" width="0pt">
7191 <column alignment="left" valignment="top" width="4.7in">
7192 <row>
7193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7194 \begin_inset Text
7195
7196 \layout Standard
7197
7198
7199 \family typewriter 
7200 eventq
7201 \end_inset 
7202 </cell>
7203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7204 \begin_inset Text
7205
7206 \layout Standard
7207
7208
7209 \series bold 
7210 input
7211 \end_inset 
7212 </cell>
7213 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7214 \begin_inset Text
7215
7216 \layout Standard
7217 \noindent 
7218 A handle for the event queue to wait on.
7219   The calling process (thread) will be blocked until 
7220 \family typewriter 
7221 eventq
7222 \family default 
7223  is not empty.
7224 \end_inset 
7225 </cell>
7226 </row>
7227 <row>
7228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7229 \begin_inset Text
7230
7231 \layout Standard
7232
7233
7234 \family typewriter 
7235 event
7236 \end_inset 
7237 </cell>
7238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7239 \begin_inset Text
7240
7241 \layout Standard
7242
7243
7244 \series bold 
7245 output
7246 \end_inset 
7247 </cell>
7248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7249 \begin_inset Text
7250
7251 \layout Standard
7252 \noindent 
7253 On successful return, this location will hold the values associated with
7254  the next event in the event queue.
7255 \end_inset 
7256 </cell>
7257 </row>
7258 </lyxtabular>
7259
7260 \end_inset 
7261
7262
7263 \layout Section
7264
7265 The Access Control Table
7266 \begin_inset LatexCommand \label{sec:ac}
7267
7268 \end_inset 
7269
7270
7271 \layout Standard
7272
7273 Processes can use the access control table to control which processes are
7274  allowed to perform operations on Portal table entries.
7275  Each communication interface has a Portal table and an access control table.
7276  The access control table for the default interface contains an entry at
7277  index zero that allows all processes with the same user id to communicate.
7278  Entries in the access control table can be manipulated using the 
7279 \emph on 
7280 PtlACEntry
7281 \emph default 
7282  function.
7283 \layout Subsection
7284
7285 PtlACEntry
7286 \begin_inset LatexCommand \label{sec:acentry}
7287
7288 \end_inset 
7289
7290
7291 \layout LyX-Code
7292
7293 int PtlACEntry( ptl_handle_ni_t  interface,
7294 \newline 
7295                 ptl_ac_index_t   index,
7296 \newline 
7297                 ptl_process_id_t matchid,
7298 \newline 
7299                 ptl_uid_t        user_id,
7300 \newline 
7301                 ptl_pt_index_t   portal );
7302 \layout Standard
7303 \noindent 
7304 The 
7305 \emph on 
7306 PtlACEntry
7307 \emph default 
7308  function can be used to update an entry in the access control table for
7309  an interface.
7310 \layout Subsubsection
7311
7312 Return Codes
7313 \layout Description
7314
7315 PTL_OK Indicates success.
7316  
7317 \layout Description
7318
7319 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
7320  
7321 \layout Description
7322
7323 PTL_INV_NI Indicates that 
7324 \family typewriter 
7325 interface
7326 \family default 
7327  is not a valid network interface handle.
7328  
7329 \layout Description
7330
7331 PTL_AC_INV_INDEX Indicates that 
7332 \family typewriter 
7333 index
7334 \family default 
7335  is not a valid access control table index.
7336  
7337 \layout Description
7338
7339 PTL_INV_PROC Indicates that 
7340 \family typewriter 
7341 matchid
7342 \family default 
7343  is not a valid process identifier.
7344  
7345 \layout Description
7346
7347 PTL_PT_INV_INDEX Indicates that 
7348 \family typewriter 
7349 portal
7350 \family default 
7351  is not a valid Portal table index.
7352  
7353 \layout Subsubsection
7354
7355 Arguments
7356 \layout Standard
7357
7358
7359 \begin_inset  Tabular
7360 <lyxtabular version="3" rows="5" columns="3">
7361 <features>
7362 <column alignment="right" valignment="top" width="0pt">
7363 <column alignment="center" valignment="top" width="0pt">
7364 <column alignment="left" valignment="top" width="4.7in">
7365 <row>
7366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7367 \begin_inset Text
7368
7369 \layout Standard
7370
7371
7372 \family typewriter 
7373 interface
7374 \end_inset 
7375 </cell>
7376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7377 \begin_inset Text
7378
7379 \layout Standard
7380
7381
7382 \series bold 
7383 input
7384 \end_inset 
7385 </cell>
7386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7387 \begin_inset Text
7388
7389 \layout Standard
7390 \noindent 
7391 Identifies the interface to use.
7392 \end_inset 
7393 </cell>
7394 </row>
7395 <row>
7396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7397 \begin_inset Text
7398
7399 \layout Standard
7400
7401
7402 \family typewriter 
7403 index
7404 \end_inset 
7405 </cell>
7406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7407 \begin_inset Text
7408
7409 \layout Standard
7410
7411
7412 \series bold 
7413 input
7414 \end_inset 
7415 </cell>
7416 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7417 \begin_inset Text
7418
7419 \layout Standard
7420 \noindent 
7421 The index of the entry in the access control table to update.
7422 \end_inset 
7423 </cell>
7424 </row>
7425 <row>
7426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7427 \begin_inset Text
7428
7429 \layout Standard
7430
7431
7432 \family typewriter 
7433 matchid
7434 \end_inset 
7435 </cell>
7436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7437 \begin_inset Text
7438
7439 \layout Standard
7440
7441
7442 \series bold 
7443 input
7444 \end_inset 
7445 </cell>
7446 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7447 \begin_inset Text
7448
7449 \layout Standard
7450 \noindent 
7451 Identifies the process(es) that are allowed to  perform operations.
7452  The constants 
7453 \family typewriter 
7454 PTL_PID_ANY
7455 \family default 
7456  and 
7457 \family typewriter 
7458 PTL_NID_ANY
7459 \family default 
7460  can be used to wildcard either of the ids in the 
7461 \family typewriter 
7462 ptl_process_id_t
7463 \family default 
7464  structure.
7465  
7466 \end_inset 
7467 </cell>
7468 </row>
7469 <row>
7470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7471 \begin_inset Text
7472
7473 \layout Standard
7474
7475
7476 \family typewriter 
7477 user_id
7478 \end_inset 
7479 </cell>
7480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7481 \begin_inset Text
7482
7483 \layout Standard
7484
7485
7486 \series bold 
7487 input
7488 \end_inset 
7489 </cell>
7490 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7491 \begin_inset Text
7492
7493 \layout Standard
7494 \noindent 
7495 Identifies the user that is allowed to  perform operations.
7496  The value 
7497 \family typewriter 
7498 PTL_UID_ANY
7499 \family default 
7500  can be used to wildcard the user.
7501 \end_inset 
7502 </cell>
7503 </row>
7504 <row>
7505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7506 \begin_inset Text
7507
7508 \layout Standard
7509
7510
7511 \family typewriter 
7512 portal
7513 \end_inset 
7514 </cell>
7515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7516 \begin_inset Text
7517
7518 \layout Standard
7519
7520
7521 \series bold 
7522 input
7523 \end_inset 
7524 </cell>
7525 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7526 \begin_inset Text
7527
7528 \layout Standard
7529 \noindent 
7530 Identifies the Portal index(es) that can be used.
7531   The value 
7532 \family typewriter 
7533 PTL_PT_INDEX_ANY
7534 \family default 
7535  can be used to wildcard the  Portal index.
7536 \end_inset 
7537 </cell>
7538 </row>
7539 </lyxtabular>
7540
7541 \end_inset 
7542
7543
7544 \layout Section
7545
7546 Data Movement Operations
7547 \begin_inset LatexCommand \label{sec:datamovement}
7548
7549 \end_inset 
7550
7551
7552 \layout Standard
7553
7554 The Portals API provides two data movement operations: 
7555 \emph on 
7556 PtlPut
7557 \emph default 
7558  and 
7559 \emph on 
7560 PtlGet
7561 \emph default 
7562 .
7563 \layout Subsection
7564
7565 PtlPut
7566 \begin_inset LatexCommand \label{sec:put}
7567
7568 \end_inset 
7569
7570
7571 \layout LyX-Code
7572
7573 typedef enum { PTL_ACK_REQ, PTL_NOACK_REQ } ptl_ack_req_t;
7574 \newline 
7575
7576 \newline 
7577 int PtlPut( ptl_handle_md_t  mem_desc,
7578 \newline 
7579             ptl_ack_req_t    ack_req,
7580 \newline 
7581             ptl_process_id_t target,
7582 \newline 
7583             ptl_pt_index_t   portal,
7584 \newline 
7585             ptl_ac_index_t   cookie,
7586 \newline 
7587             ptl_match_bits_t match_bits,
7588 \newline 
7589             ptl_size_t       offset,
7590 \newline 
7591             ptl_hdr_data_t   hdr_data );
7592 \layout Standard
7593 \noindent 
7594 Values of the type 
7595 \family typewriter 
7596 ptl_ack_req_t
7597 \family default 
7598  are used to control whether an acknowledgement should be sent when the
7599  operation completes (i.e., when the data has been written to a memory descriptor
7600  of the 
7601 \family typewriter 
7602 target
7603 \family default 
7604  process).
7605  The value 
7606 \family typewriter 
7607 PTL_ACK_REQ
7608 \family default 
7609  requests an acknowledgement, the value 
7610 \family typewriter 
7611 PTL_NOACK_REQ
7612 \family default 
7613  requests that no acknowledgement should be generated.
7614 \layout Standard
7615
7616 The 
7617 \emph on 
7618 PtlPut
7619 \emph default 
7620  function initiates an asynchronous put operation.
7621  There are several events associated with a put operation: initiation of
7622  the send on the local node (
7623 \family typewriter 
7624 PTL_EVENT_SEND_START
7625 \family default 
7626 ), completion of the send on the local node (
7627 \family typewriter 
7628 PTL_EVENT_SEND_END
7629 \family default 
7630  or 
7631 \family typewriter 
7632 PTL_EVENT_SEND_FAIL
7633 \family default 
7634 ), and, when the send completes successfully, the receipt of an acknowledgement
7635  (
7636 \family typewriter 
7637 PTL_EVENT_ACK
7638 \family default 
7639 ) indicating that the operation was accepted by the target.
7640  These events will be logged in the event queue associated with the memory
7641  descriptor (
7642 \family typewriter 
7643 mem_desc
7644 \family default 
7645 ) used in the put operation.
7646  Using a memory descriptor that does not have an associated event queue
7647  results in these events being discarded.
7648  In this case, the application must have another mechanism (e.g., a higher
7649  level protocol) for determining when it is safe to modify the memory region
7650  associated with the memory descriptor.
7651 \layout Subsubsection
7652
7653 Return Codes
7654 \layout Description
7655
7656 PTL_OK Indicates success.
7657  
7658 \layout Description
7659
7660 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
7661  
7662 \layout Description
7663
7664 PTL_INV_MD Indicates that 
7665 \family typewriter 
7666 mem_desc
7667 \family default 
7668  is not a valid memory descriptor.
7669  
7670 \layout Description
7671
7672 PTL_INV_PROC Indicates that 
7673 \family typewriter 
7674 target
7675 \family default 
7676  is not a valid process id.
7677  
7678 \layout Subsubsection
7679
7680 Arguments
7681 \layout Standard
7682
7683
7684 \begin_inset  Tabular
7685 <lyxtabular version="3" rows="8" columns="3">
7686 <features>
7687 <column alignment="center" valignment="top" width="0pt">
7688 <column alignment="center" valignment="top" width="0pt">
7689 <column alignment="left" valignment="top" width="4.7in">
7690 <row>
7691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7692 \begin_inset Text
7693
7694 \layout Standard
7695
7696
7697 \family typewriter 
7698 mem_desc
7699 \end_inset 
7700 </cell>
7701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7702 \begin_inset Text
7703
7704 \layout Standard
7705
7706
7707 \series bold 
7708 input
7709 \end_inset 
7710 </cell>
7711 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7712 \begin_inset Text
7713
7714 \layout Standard
7715 \noindent 
7716 A handle for the memory descriptor that describes the memory to be sent.
7717   If the memory descriptor has an event queue  associated with it, it will
7718  be used to record events when the  message has been sent (PTL_EVENT_SEND_START,
7719  PTL_EVENT_SEND_END).
7720  
7721 \end_inset 
7722 </cell>
7723 </row>
7724 <row>
7725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7726 \begin_inset Text
7727
7728 \layout Standard
7729
7730
7731 \family typewriter 
7732 ack_req
7733 \end_inset 
7734 </cell>
7735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7736 \begin_inset Text
7737
7738 \layout Standard
7739
7740
7741 \series bold 
7742 input
7743 \end_inset 
7744 </cell>
7745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7746 \begin_inset Text
7747
7748 \layout Standard
7749 \noindent 
7750 Controls whether an acknowledgement event is requested.
7751   Acknowledgements are only sent when they are requested by the initiating
7752  process 
7753 \series bold 
7754 and
7755 \series default 
7756  the memory descriptor has an event queue 
7757 \series bold 
7758 and
7759 \series default 
7760  the target memory descriptor enables them.
7761  Allowed constants: 
7762 \family typewriter 
7763 PTL_ACK_REQ
7764 \family default 
7765
7766 \family typewriter 
7767 PTL_NOACK_REQ
7768 \family default 
7769 .
7770 \end_inset 
7771 </cell>
7772 </row>
7773 <row>
7774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7775 \begin_inset Text
7776
7777 \layout Standard
7778
7779
7780 \family typewriter 
7781 target
7782 \end_inset 
7783 </cell>
7784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7785 \begin_inset Text
7786
7787 \layout Standard
7788
7789
7790 \series bold 
7791 input
7792 \end_inset 
7793 </cell>
7794 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7795 \begin_inset Text
7796
7797 \layout Standard
7798 \noindent 
7799 A process id for the target process.
7800 \end_inset 
7801 </cell>
7802 </row>
7803 <row>
7804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7805 \begin_inset Text
7806
7807 \layout Standard
7808
7809
7810 \family typewriter 
7811 portal
7812 \end_inset 
7813 </cell>
7814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7815 \begin_inset Text
7816
7817 \layout Standard
7818
7819
7820 \series bold 
7821 input
7822 \end_inset 
7823 </cell>
7824 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7825 \begin_inset Text
7826
7827 \layout Standard
7828 \noindent 
7829 The index in the remote Portal table.
7830 \end_inset 
7831 </cell>
7832 </row>
7833 <row>
7834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7835 \begin_inset Text
7836
7837 \layout Standard
7838
7839
7840 \family typewriter 
7841 cookie
7842 \end_inset 
7843 </cell>
7844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7845 \begin_inset Text
7846
7847 \layout Standard
7848
7849
7850 \series bold 
7851 input
7852 \end_inset 
7853 </cell>
7854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7855 \begin_inset Text
7856
7857 \layout Standard
7858 \noindent 
7859 The index into the access control table of the target process.
7860 \end_inset 
7861 </cell>
7862 </row>
7863 <row>
7864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7865 \begin_inset Text
7866
7867 \layout Standard
7868
7869
7870 \family typewriter 
7871 match_bits
7872 \end_inset 
7873 </cell>
7874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7875 \begin_inset Text
7876
7877 \layout Standard
7878
7879
7880 \series bold 
7881 input
7882 \end_inset 
7883 </cell>
7884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7885 \begin_inset Text
7886
7887 \layout Standard
7888 \noindent 
7889 The match bits to use for message selection at the target process.
7890 \end_inset 
7891 </cell>
7892 </row>
7893 <row>
7894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7895 \begin_inset Text
7896
7897 \layout Standard
7898
7899
7900 \family typewriter 
7901 offset
7902 \end_inset 
7903 </cell>
7904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7905 \begin_inset Text
7906
7907 \layout Standard
7908
7909
7910 \series bold 
7911 input
7912 \end_inset 
7913 </cell>
7914 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7915 \begin_inset Text
7916
7917 \layout Standard
7918 \noindent 
7919 The offset into the target memory descriptor (only used when the target
7920  memory descriptor has the 
7921 \family typewriter 
7922 PTL_MD_MANAGE_REMOTE
7923 \family default 
7924  option set).
7925 \end_inset 
7926 </cell>
7927 </row>
7928 <row>
7929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7930 \begin_inset Text
7931
7932 \layout Standard
7933
7934
7935 \family typewriter 
7936 hdr_data
7937 \end_inset 
7938 </cell>
7939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7940 \begin_inset Text
7941
7942 \layout Standard
7943
7944
7945 \series bold 
7946 input
7947 \end_inset 
7948 </cell>
7949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7950 \begin_inset Text
7951
7952 \layout Standard
7953 \noindent 
7954 64 bits of user data that can be included in message header.
7955   This data is written to an event queue entry at the target if an event
7956  queue is present on the matching memory descriptor.
7957 \end_inset 
7958 </cell>
7959 </row>
7960 </lyxtabular>
7961
7962 \end_inset 
7963
7964
7965 \layout Subsection
7966
7967 PtlGet
7968 \begin_inset LatexCommand \label{sec:get}
7969
7970 \end_inset 
7971
7972
7973 \layout LyX-Code
7974
7975 int PtlGet( ptl_handle_md_t  mem_desc,
7976 \newline 
7977             ptl_process_id_t target,
7978 \newline 
7979             ptl_pt_index_t   portal,
7980 \newline 
7981             ptl_ac_index_t   cookie,
7982 \newline 
7983             ptl_match_bits_t match_bits,
7984 \newline 
7985             ptl_size_t       offset );
7986 \layout Standard
7987 \noindent 
7988 The 
7989 \emph on 
7990 PtlGet
7991 \emph default 
7992  function initiates a remote read operation.
7993  There are two event pairs associated with a get operation , when the data
7994  is sent from the remote node, a 
7995 \family typewriter 
7996 PTL_EVENT_GET{START|END}
7997 \family default 
7998  event pair is registered on the remote node; and when the data is returned
7999  from the remote node a 
8000 \family typewriter 
8001 PTL_EVENT_REPLY{START|END}
8002 \family default 
8003  event pair is registered on the local node.
8004 \layout Subsubsection
8005
8006 Return Codes
8007 \layout Description
8008
8009 PTL_OK Indicates success.
8010  
8011 \layout Description
8012
8013 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
8014  
8015 \layout Description
8016
8017 PTL_INV_MD Indicates that 
8018 \family typewriter 
8019 mem_desc
8020 \family default 
8021  is not a valid memory descriptor.
8022  
8023 \layout Description
8024
8025 PTL_INV_PROC Indicates that 
8026 \family typewriter 
8027 target
8028 \family default 
8029  is not a valid process id.
8030  
8031 \layout Subsubsection
8032
8033 Arguments
8034 \layout Standard
8035
8036
8037 \begin_inset  Tabular
8038 <lyxtabular version="3" rows="6" columns="3">
8039 <features>
8040 <column alignment="right" valignment="top" width="0pt">
8041 <column alignment="center" valignment="top" width="0pt">
8042 <column alignment="left" valignment="top" width="4.7in">
8043 <row>
8044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8045 \begin_inset Text
8046
8047 \layout Standard
8048
8049
8050 \family typewriter 
8051 mem_desc
8052 \end_inset 
8053 </cell>
8054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8055 \begin_inset Text
8056
8057 \layout Standard
8058
8059
8060 \series bold 
8061 input
8062 \end_inset 
8063 </cell>
8064 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8065 \begin_inset Text
8066
8067 \layout Standard
8068 \noindent 
8069 A handle for the memory descriptor that describes the memory into which
8070  the requested data will be received.
8071   The memory descriptor can have an event queue associated with it to record
8072  events, such as when the message receive has started (
8073 \family typewriter 
8074 PTL_EVENT_REPLY
8075 \family default 
8076 _
8077 \family typewriter 
8078 START
8079 \family default 
8080 ).
8081 \end_inset 
8082 </cell>
8083 </row>
8084 <row>
8085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8086 \begin_inset Text
8087
8088 \layout Standard
8089
8090
8091 \family typewriter 
8092 target
8093 \end_inset 
8094 </cell>
8095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8096 \begin_inset Text
8097
8098 \layout Standard
8099
8100
8101 \series bold 
8102 input
8103 \end_inset 
8104 </cell>
8105 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8106 \begin_inset Text
8107
8108 \layout Standard
8109 \noindent 
8110 A process id for the target process.
8111 \end_inset 
8112 </cell>
8113 </row>
8114 <row>
8115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8116 \begin_inset Text
8117
8118 \layout Standard
8119
8120
8121 \family typewriter 
8122 portal
8123 \end_inset 
8124 </cell>
8125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8126 \begin_inset Text
8127
8128 \layout Standard
8129
8130
8131 \series bold 
8132 input
8133 \end_inset 
8134 </cell>
8135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8136 \begin_inset Text
8137
8138 \layout Standard
8139 \noindent 
8140 The index in the remote Portal table.
8141 \end_inset 
8142 </cell>
8143 </row>
8144 <row>
8145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8146 \begin_inset Text
8147
8148 \layout Standard
8149
8150
8151 \family typewriter 
8152 cookie
8153 \end_inset 
8154 </cell>
8155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8156 \begin_inset Text
8157
8158 \layout Standard
8159
8160
8161 \series bold 
8162 input
8163 \end_inset 
8164 </cell>
8165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8166 \begin_inset Text
8167
8168 \layout Standard
8169 \noindent 
8170 The index into the access control table of the target process.
8171 \end_inset 
8172 </cell>
8173 </row>
8174 <row>
8175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8176 \begin_inset Text
8177
8178 \layout Standard
8179
8180
8181 \family typewriter 
8182 match_bits
8183 \end_inset 
8184 </cell>
8185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8186 \begin_inset Text
8187
8188 \layout Standard
8189
8190
8191 \series bold 
8192 input
8193 \end_inset 
8194 </cell>
8195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8196 \begin_inset Text
8197
8198 \layout Standard
8199 \noindent 
8200 The match bits to use for message selection at the target process.
8201 \end_inset 
8202 </cell>
8203 </row>
8204 <row>
8205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8206 \begin_inset Text
8207
8208 \layout Standard
8209
8210
8211 \family typewriter 
8212 offset
8213 \end_inset 
8214 </cell>
8215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8216 \begin_inset Text
8217
8218 \layout Standard
8219
8220
8221 \series bold 
8222 input
8223 \end_inset 
8224 </cell>
8225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8226 \begin_inset Text
8227
8228 \layout Standard
8229 \noindent 
8230 The offset into the target memory descriptor (only used when the target
8231  memory descriptor has the 
8232 \family typewriter 
8233 PTL_MD_MANAGE_REMOTE
8234 \family default 
8235  option set).
8236 \end_inset 
8237 </cell>
8238 </row>
8239 </lyxtabular>
8240
8241 \end_inset 
8242
8243
8244 \layout Section
8245
8246 Summary
8247 \layout Standard
8248
8249
8250 \begin_inset LatexCommand \label{sec:summary}
8251
8252 \end_inset 
8253
8254  We conclude this section by summarizing the names introduced by the Portals
8255  3.2 API.
8256  We start by summarizing the names of the types introduced by the API.
8257  This is followed by a summary of the functions introduced by the API.
8258  Which is followed by a summary of the function return codes.
8259  Finally, we conclude with a summary of the other constant values introduced
8260  by the API.
8261 \layout Standard
8262
8263 Table\SpecialChar ~
8264
8265 \begin_inset LatexCommand \ref{tab:types}
8266
8267 \end_inset 
8268
8269  presents a summary of the types defined by the Portals API.
8270  The first column in this table gives the type name, the second column gives
8271  a brief description of the type, the third column identifies the section
8272  where the type is defined, and the fourth column lists the functions that
8273  have arguments of this type.
8274 \layout Standard
8275
8276
8277 \begin_inset Float table
8278 placement htbp
8279 wide false
8280 collapsed false
8281
8282 \layout Caption
8283
8284 Types Defined by the Portals 3.2 API
8285 \begin_inset LatexCommand \label{tab:types}
8286
8287 \end_inset 
8288
8289
8290 \layout Standard
8291
8292
8293 \begin_inset ERT
8294 status Collapsed
8295
8296 \layout Standard
8297
8298 \backslash 
8299 medskip  
8300 \end_inset 
8301
8302
8303 \layout Standard
8304 \noindent 
8305
8306 \size small 
8307
8308 \begin_inset  Tabular
8309 <lyxtabular version="3" rows="25" columns="4">
8310 <features firstHeadEmpty="true">
8311 <column alignment="left" valignment="top" width="0pt">
8312 <column alignment="left" valignment="top" width="2in">
8313 <column alignment="left" valignment="top" width="0pt">
8314 <column alignment="left" valignment="top" width="2.2in">
8315 <row bottomline="true">
8316 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8317 \begin_inset Text
8318
8319 \layout Standard
8320
8321
8322 \series bold 
8323  Name
8324 \end_inset 
8325 </cell>
8326 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8327 \begin_inset Text
8328
8329 \layout Standard
8330
8331
8332 \series bold 
8333  Meaning 
8334 \end_inset 
8335 </cell>
8336 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8337 \begin_inset Text
8338
8339 \layout Standard
8340
8341
8342 \series bold 
8343  Sect
8344 \end_inset 
8345 </cell>
8346 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8347 \begin_inset Text
8348
8349 \layout Standard
8350
8351
8352 \series bold 
8353  Functions 
8354 \end_inset 
8355 </cell>
8356 </row>
8357 <row>
8358 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8359 \begin_inset Text
8360
8361 \layout Standard
8362
8363
8364 \family typewriter 
8365 ptl_ac_index_t 
8366 \end_inset 
8367 </cell>
8368 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8369 \begin_inset Text
8370
8371 \layout Standard
8372 \noindent 
8373 indexes for an access control table 
8374 \end_inset 
8375 </cell>
8376 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8377 \begin_inset Text
8378
8379 \layout Standard
8380
8381
8382 \begin_inset LatexCommand \ref{sec:index-type}
8383
8384 \end_inset 
8385
8386
8387 \end_inset 
8388 </cell>
8389 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8390 \begin_inset Text
8391
8392 \layout Standard
8393 \noindent 
8394 PtlACEntry, PtlPut, PtlGet 
8395 \end_inset 
8396 </cell>
8397 </row>
8398 <row>
8399 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8400 \begin_inset Text
8401
8402 \layout Standard
8403
8404
8405 \family typewriter 
8406 ptl_ack_req_t 
8407 \end_inset 
8408 </cell>
8409 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8410 \begin_inset Text
8411
8412 \layout Standard
8413 \noindent 
8414 acknowledgement request types 
8415 \end_inset 
8416 </cell>
8417 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8418 \begin_inset Text
8419
8420 \layout Standard
8421
8422
8423 \begin_inset LatexCommand \ref{sec:put}
8424
8425 \end_inset 
8426
8427
8428 \end_inset 
8429 </cell>
8430 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8431 \begin_inset Text
8432
8433 \layout Standard
8434 \noindent 
8435 PtlPut
8436 \end_inset 
8437 </cell>
8438 </row>
8439 <row>
8440 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8441 \begin_inset Text
8442
8443 \layout Standard
8444
8445
8446 \family typewriter 
8447 ptl_event_kind_t
8448 \family default 
8449  
8450 \end_inset 
8451 </cell>
8452 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8453 \begin_inset Text
8454
8455 \layout Standard
8456 \noindent 
8457 kinds of events
8458 \end_inset 
8459 </cell>
8460 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8461 \begin_inset Text
8462
8463 \layout Standard
8464
8465
8466 \begin_inset LatexCommand \ref{sec:ek-type}
8467
8468 \end_inset 
8469
8470
8471 \end_inset 
8472 </cell>
8473 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8474 \begin_inset Text
8475
8476 \layout Standard
8477 \noindent 
8478 PtlGet
8479 \end_inset 
8480 </cell>
8481 </row>
8482 <row>
8483 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8484 \begin_inset Text
8485
8486 \layout Standard
8487
8488
8489 \family typewriter 
8490 ptl_event_t 
8491 \end_inset 
8492 </cell>
8493 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8494 \begin_inset Text
8495
8496 \layout Standard
8497 \noindent 
8498 information about events 
8499 \end_inset 
8500 </cell>
8501 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8502 \begin_inset Text
8503
8504 \layout Standard
8505
8506
8507 \begin_inset LatexCommand \ref{sec:event-type}
8508
8509 \end_inset 
8510
8511
8512 \end_inset 
8513 </cell>
8514 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8515 \begin_inset Text
8516
8517 \layout Standard
8518 \noindent 
8519 PtlEQGet
8520 \end_inset 
8521 </cell>
8522 </row>
8523 <row>
8524 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8525 \begin_inset Text
8526
8527 \layout Standard
8528
8529
8530 \family typewriter 
8531 plt_seq_t
8532 \end_inset 
8533 </cell>
8534 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8535 \begin_inset Text
8536
8537 \layout Standard
8538
8539 event sequence number
8540 \end_inset 
8541 </cell>
8542 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8543 \begin_inset Text
8544
8545 \layout Standard
8546
8547
8548 \begin_inset LatexCommand \ref{sec:event-type}
8549
8550 \end_inset 
8551
8552
8553 \end_inset 
8554 </cell>
8555 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8556 \begin_inset Text
8557
8558 \layout Standard
8559
8560 PtlEQGet, PtlEQWait
8561 \end_inset 
8562 </cell>
8563 </row>
8564 <row>
8565 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8566 \begin_inset Text
8567
8568 \layout Standard
8569
8570
8571 \family typewriter 
8572 ptl_handle_any_t 
8573 \end_inset 
8574 </cell>
8575 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8576 \begin_inset Text
8577
8578 \layout Standard
8579 \noindent 
8580 handles for any object 
8581 \end_inset 
8582 </cell>
8583 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
8584 \begin_inset Text
8585
8586 \layout Standard
8587
8588  
8589 \begin_inset LatexCommand \ref{sec:handle-type}
8590
8591 \end_inset 
8592
8593
8594 \end_inset 
8595 </cell>
8596 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
8597 \begin_inset Text
8598
8599 \layout Standard
8600 \noindent 
8601 PtlNIHandle 
8602 \end_inset 
8603 </cell>
8604 </row>
8605 <row>
8606 <cell alignment="right" valignment="top" usebox="none">
8607 \begin_inset Text
8608
8609 \layout Standard
8610
8611
8612 \family typewriter 
8613 ptl_handle_eq_t 
8614 \end_inset 
8615 </cell>
8616 <cell alignment="left" valignment="top" usebox="none">
8617 \begin_inset Text
8618
8619 \layout Standard
8620 \noindent 
8621 handles for event queues 
8622 \end_inset 
8623 </cell>
8624 <cell alignment="right" valignment="top" usebox="none">
8625 \begin_inset Text
8626
8627 \layout Standard
8628
8629  
8630 \begin_inset LatexCommand \ref{sec:handle-type}
8631
8632 \end_inset 
8633
8634
8635 \end_inset 
8636 </cell>
8637 <cell alignment="left" valignment="top" usebox="none">
8638 \begin_inset Text
8639
8640 \layout Standard
8641 \noindent 
8642 PtlEQAlloc, PtlEQFree, PtlEQGet, PtlEQWait, PtlMDUpdate 
8643 \end_inset 
8644 </cell>
8645 </row>
8646 <row>
8647 <cell alignment="right" valignment="top" usebox="none">
8648 \begin_inset Text
8649
8650 \layout Standard
8651
8652
8653 \family typewriter 
8654 ptl_handle_md_t
8655 \family default 
8656  
8657 \end_inset 
8658 </cell>
8659 <cell alignment="left" valignment="top" usebox="none">
8660 \begin_inset Text
8661
8662 \layout Standard
8663 \noindent 
8664 handles for memory descriptors 
8665 \end_inset 
8666 </cell>
8667 <cell alignment="right" valignment="top" usebox="none">
8668 \begin_inset Text
8669
8670 \layout Standard
8671
8672  
8673 \begin_inset LatexCommand \ref{sec:handle-type}
8674
8675 \end_inset 
8676
8677
8678 \end_inset 
8679 </cell>
8680 <cell alignment="left" valignment="top" usebox="none">
8681 \begin_inset Text
8682
8683 \layout Standard
8684 \noindent 
8685 PtlMDAlloc, PtlMDUnlink, PtlMDUpdate, PtlMEAttach, PtlMEAttachAny, PtlMEInsert,
8686  PtlPut, PtlGet 
8687 \end_inset 
8688 </cell>
8689 </row>
8690 <row>
8691 <cell alignment="right" valignment="top" usebox="none">
8692 \begin_inset Text
8693
8694 \layout Standard
8695
8696
8697 \family typewriter 
8698 ptl_handle_me_t
8699 \family default 
8700  
8701 \end_inset 
8702 </cell>
8703 <cell alignment="left" valignment="top" usebox="none">
8704 \begin_inset Text
8705
8706 \layout Standard
8707 \noindent 
8708 handles for match entries 
8709 \end_inset 
8710 </cell>
8711 <cell alignment="right" valignment="top" usebox="none">
8712 \begin_inset Text
8713
8714 \layout Standard
8715
8716  
8717 \begin_inset LatexCommand \ref{sec:handle-type}
8718
8719 \end_inset 
8720
8721
8722 \end_inset 
8723 </cell>
8724 <cell alignment="left" valignment="top" usebox="none">
8725 \begin_inset Text
8726
8727 \layout Standard
8728 \noindent 
8729 PtlMEAttach, PtlMEAttachAny, PtlMEInsert, PtlMEUnlink 
8730 \end_inset 
8731 </cell>
8732 </row>
8733 <row>
8734 <cell alignment="right" valignment="top" usebox="none">
8735 \begin_inset Text
8736
8737 \layout Standard
8738
8739
8740 \family typewriter 
8741 ptl_handle_ni_t 
8742 \end_inset 
8743 </cell>
8744 <cell alignment="left" valignment="top" usebox="none">
8745 \begin_inset Text
8746
8747 \layout Standard
8748 \noindent 
8749 handles for network interfaces 
8750 \end_inset 
8751 </cell>
8752 <cell alignment="right" valignment="top" usebox="none">
8753 \begin_inset Text
8754
8755 \layout Standard
8756
8757  
8758 \begin_inset LatexCommand \ref{sec:handle-type}
8759
8760 \end_inset 
8761
8762
8763 \end_inset 
8764 </cell>
8765 <cell alignment="left" valignment="top" usebox="none">
8766 \begin_inset Text
8767
8768 \layout Standard
8769 \noindent 
8770 PtlNIInit, PtlNIFini, PtlNIStatus, PtlNIDist, PtlEQAlloc, PtlACEntry, PtlPut,
8771  PtlGet 
8772 \end_inset 
8773 </cell>
8774 </row>
8775 <row>
8776 <cell alignment="right" valignment="top" usebox="none">
8777 \begin_inset Text
8778
8779 \layout Standard
8780
8781
8782 \family typewriter 
8783 ptl_nid_t
8784 \family default 
8785  
8786 \end_inset 
8787 </cell>
8788 <cell alignment="left" valignment="top" usebox="none">
8789 \begin_inset Text
8790
8791 \layout Standard
8792 \noindent 
8793 node identifiers
8794 \end_inset 
8795 </cell>
8796 <cell alignment="right" valignment="top" usebox="none">
8797 \begin_inset Text
8798
8799 \layout Standard
8800
8801  
8802 \begin_inset LatexCommand \ref{sec:id-type}
8803
8804 \end_inset 
8805
8806
8807 \end_inset 
8808 </cell>
8809 <cell alignment="left" valignment="top" usebox="none">
8810 \begin_inset Text
8811
8812 \layout Standard
8813 \noindent 
8814  PtlGetId,PtlACEntry
8815 \end_inset 
8816 </cell>
8817 </row>
8818 <row>
8819 <cell alignment="right" valignment="top" usebox="none">
8820 \begin_inset Text
8821
8822 \layout Standard
8823
8824
8825 \family typewriter 
8826 ptl_pid_t
8827 \end_inset 
8828 </cell>
8829 <cell alignment="left" valignment="top" usebox="none">
8830 \begin_inset Text
8831
8832 \layout Standard
8833
8834 process identifier
8835 \end_inset 
8836 </cell>
8837 <cell alignment="right" valignment="top" usebox="none">
8838 \begin_inset Text
8839
8840 \layout Standard
8841
8842
8843 \begin_inset LatexCommand \ref{sec:id-type}
8844
8845 \end_inset 
8846
8847
8848 \end_inset 
8849 </cell>
8850 <cell alignment="left" valignment="top" usebox="none">
8851 \begin_inset Text
8852
8853 \layout Standard
8854
8855 PtlGetId, PtlACEntry
8856 \end_inset 
8857 </cell>
8858 </row>
8859 <row>
8860 <cell alignment="right" valignment="top" usebox="none">
8861 \begin_inset Text
8862
8863 \layout Standard
8864
8865
8866 \family typewriter 
8867 ptl_uid_t
8868 \end_inset 
8869 </cell>
8870 <cell alignment="left" valignment="top" usebox="none">
8871 \begin_inset Text
8872
8873 \layout Standard
8874
8875 user indentifier
8876 \end_inset 
8877 </cell>
8878 <cell alignment="right" valignment="top" usebox="none">
8879 \begin_inset Text
8880
8881 \layout Standard
8882
8883
8884 \begin_inset LatexCommand \ref{sec:id-type}
8885
8886 \end_inset 
8887
8888
8889 \end_inset 
8890 </cell>
8891 <cell alignment="left" valignment="top" usebox="none">
8892 \begin_inset Text
8893
8894 \layout Standard
8895
8896 PtlGetUid, PtlACEntry
8897 \end_inset 
8898 </cell>
8899 </row>
8900 <row>
8901 <cell alignment="right" valignment="top" usebox="none">
8902 \begin_inset Text
8903
8904 \layout Standard
8905
8906
8907 \family typewriter 
8908 ptl_ins_pos_t 
8909 \end_inset 
8910 </cell>
8911 <cell alignment="left" valignment="top" usebox="none">
8912 \begin_inset Text
8913
8914 \layout Standard
8915 \noindent 
8916 insertion position (before or after) 
8917 \end_inset 
8918 </cell>
8919 <cell alignment="right" valignment="top" usebox="none">
8920 \begin_inset Text
8921
8922 \layout Standard
8923
8924  
8925 \begin_inset LatexCommand \ref{sec:meattach}
8926
8927 \end_inset 
8928
8929
8930 \end_inset 
8931 </cell>
8932 <cell alignment="left" valignment="top" usebox="none">
8933 \begin_inset Text
8934
8935 \layout Standard
8936 \noindent 
8937 PtlMEAttach, PtlMEAttachAny, PtlMEInsert 
8938 \end_inset 
8939 </cell>
8940 </row>
8941 <row>
8942 <cell alignment="right" valignment="top" usebox="none">
8943 \begin_inset Text
8944
8945 \layout Standard
8946
8947
8948 \family typewriter 
8949 ptl_interface_t 
8950 \end_inset 
8951 </cell>
8952 <cell alignment="left" valignment="top" usebox="none">
8953 \begin_inset Text
8954
8955 \layout Standard
8956 \noindent 
8957 identifiers for network interfaces 
8958 \end_inset 
8959 </cell>
8960 <cell alignment="right" valignment="top" usebox="none">
8961 \begin_inset Text
8962
8963 \layout Standard
8964
8965  
8966 \begin_inset LatexCommand \ref{sec:ni-type}
8967
8968 \end_inset 
8969
8970
8971 \end_inset 
8972 </cell>
8973 <cell alignment="left" valignment="top" usebox="none">
8974 \begin_inset Text
8975
8976 \layout Standard
8977 \noindent 
8978 PtlNIInit 
8979 \end_inset 
8980 </cell>
8981 </row>
8982 <row>
8983 <cell alignment="right" valignment="top" usebox="none">
8984 \begin_inset Text
8985
8986 \layout Standard
8987
8988
8989 \family typewriter 
8990 ptl_match_bits_t
8991 \family default 
8992  
8993 \end_inset 
8994 </cell>
8995 <cell alignment="left" valignment="top" usebox="none">
8996 \begin_inset Text
8997
8998 \layout Standard
8999 \noindent 
9000 match (and ignore) bits 
9001 \end_inset 
9002 </cell>
9003 <cell alignment="right" valignment="top" usebox="none">
9004 \begin_inset Text
9005
9006 \layout Standard
9007
9008  
9009 \begin_inset LatexCommand \ref{sec:mb-type}
9010
9011 \end_inset 
9012
9013
9014 \end_inset 
9015 </cell>
9016 <cell alignment="left" valignment="top" usebox="none">
9017 \begin_inset Text
9018
9019 \layout Standard
9020 \noindent 
9021 PtlMEAttach, PtlMEAttachAny, PtlMEInsert, PtlPut, PtlGet 
9022 \end_inset 
9023 </cell>
9024 </row>
9025 <row>
9026 <cell alignment="right" valignment="top" usebox="none">
9027 \begin_inset Text
9028
9029 \layout Standard
9030
9031  
9032 \family typewriter 
9033 ptl_md_t
9034 \family default 
9035  
9036 \end_inset 
9037 </cell>
9038 <cell alignment="left" valignment="top" usebox="none">
9039 \begin_inset Text
9040
9041 \layout Standard
9042 \noindent 
9043 memory descriptors 
9044 \end_inset 
9045 </cell>
9046 <cell alignment="right" valignment="top" usebox="none">
9047 \begin_inset Text
9048
9049 \layout Standard
9050
9051  
9052 \begin_inset LatexCommand \ref{sec:md-type}
9053
9054 \end_inset 
9055
9056
9057 \end_inset 
9058 </cell>
9059 <cell alignment="left" valignment="top" usebox="none">
9060 \begin_inset Text
9061
9062 \layout Standard
9063 \noindent 
9064 PtlMDAttach, PtlMDUpdate 
9065 \end_inset 
9066 </cell>
9067 </row>
9068 <row>
9069 <cell alignment="right" valignment="top" usebox="none">
9070 \begin_inset Text
9071
9072 \layout Standard
9073
9074
9075 \family typewriter 
9076 ptl_ni_fail_t
9077 \end_inset 
9078 </cell>
9079 <cell alignment="left" valignment="top" usebox="none">
9080 \begin_inset Text
9081
9082 \layout Standard
9083
9084 network interface-specific failures
9085 \end_inset 
9086 </cell>
9087 <cell alignment="right" valignment="top" usebox="none">
9088 \begin_inset Text
9089
9090 \layout Standard
9091
9092
9093 \begin_inset LatexCommand \ref{sec:eq}
9094
9095 \end_inset 
9096
9097
9098 \end_inset 
9099 </cell>
9100 <cell alignment="left" valignment="top" usebox="none">
9101 \begin_inset Text
9102
9103 \layout Standard
9104
9105 PtlEQGet, PtlEQWait
9106 \end_inset 
9107 </cell>
9108 </row>
9109 <row>
9110 <cell alignment="right" valignment="top" usebox="none">
9111 \begin_inset Text
9112
9113 \layout Standard
9114
9115
9116 \family typewriter 
9117 ptl_process_id_t
9118 \family default 
9119  
9120 \end_inset 
9121 </cell>
9122 <cell alignment="left" valignment="top" usebox="none">
9123 \begin_inset Text
9124
9125 \layout Standard
9126 \noindent 
9127 process identifiers 
9128 \end_inset 
9129 </cell>
9130 <cell alignment="right" valignment="top" usebox="none">
9131 \begin_inset Text
9132
9133 \layout Standard
9134
9135  
9136 \begin_inset LatexCommand \ref{sec:pid-type}
9137
9138 \end_inset 
9139
9140
9141 \end_inset 
9142 </cell>
9143 <cell alignment="left" valignment="top" usebox="none">
9144 \begin_inset Text
9145
9146 \layout Standard
9147 \noindent 
9148 PtlGetId, PtlNIDist, PtlMEAttach, PtlMEAttachAny, PtlACEntry, PtlPut, PtlGet
9149  
9150 \end_inset 
9151 </cell>
9152 </row>
9153 <row>
9154 <cell alignment="right" valignment="top" usebox="none">
9155 \begin_inset Text
9156
9157 \layout Standard
9158
9159
9160 \family typewriter 
9161 ptl_pt_index_t 
9162 \end_inset 
9163 </cell>
9164 <cell alignment="left" valignment="top" usebox="none">
9165 \begin_inset Text
9166
9167 \layout Standard
9168 \noindent 
9169 indexes for Portal tables 
9170 \end_inset 
9171 </cell>
9172 <cell alignment="right" valignment="top" usebox="none">
9173 \begin_inset Text
9174
9175 \layout Standard
9176
9177  
9178 \begin_inset LatexCommand \ref{sec:index-type}
9179
9180 \end_inset 
9181
9182
9183 \end_inset 
9184 </cell>
9185 <cell alignment="left" valignment="top" usebox="none">
9186 \begin_inset Text
9187
9188 \layout Standard
9189 \noindent 
9190 PtlMEAttach, PtlMEAttachAny, PtlACEntry 
9191 \end_inset 
9192 </cell>
9193 </row>
9194 <row>
9195 <cell alignment="right" valignment="top" usebox="none">
9196 \begin_inset Text
9197
9198 \layout Standard
9199
9200
9201 \family typewriter 
9202 ptl_size_t
9203 \family default 
9204  
9205 \end_inset 
9206 </cell>
9207 <cell alignment="left" valignment="top" usebox="none">
9208 \begin_inset Text
9209
9210 \layout Standard
9211 \noindent 
9212 sizes 
9213 \end_inset 
9214 </cell>
9215 <cell alignment="right" valignment="top" usebox="none">
9216 \begin_inset Text
9217
9218 \layout Standard
9219
9220  
9221 \begin_inset LatexCommand \ref{sec:size-t}
9222
9223 \end_inset 
9224
9225
9226 \end_inset 
9227 </cell>
9228 <cell alignment="left" valignment="top" usebox="none">
9229 \begin_inset Text
9230
9231 \layout Standard
9232 \noindent 
9233 PtlEQAlloc, PtlPut, PtlGet 
9234 \end_inset 
9235 </cell>
9236 </row>
9237 <row>
9238 <cell alignment="right" valignment="top" usebox="none">
9239 \begin_inset Text
9240
9241 \layout Standard
9242
9243
9244 \family typewriter 
9245 ptl_sr_index_t 
9246 \end_inset 
9247 </cell>
9248 <cell alignment="left" valignment="top" usebox="none">
9249 \begin_inset Text
9250
9251 \layout Standard
9252 \noindent 
9253 indexes for status registers 
9254 \end_inset 
9255 </cell>
9256 <cell alignment="right" valignment="top" usebox="none">
9257 \begin_inset Text
9258
9259 \layout Standard
9260
9261  
9262 \begin_inset LatexCommand \ref{sec:stat-type}
9263
9264 \end_inset 
9265
9266
9267 \end_inset 
9268 </cell>
9269 <cell alignment="left" valignment="top" usebox="none">
9270 \begin_inset Text
9271
9272 \layout Standard
9273 \noindent 
9274 PtlNIStatus 
9275 \end_inset 
9276 </cell>
9277 </row>
9278 <row>
9279 <cell alignment="right" valignment="top" usebox="none">
9280 \begin_inset Text
9281
9282 \layout Standard
9283
9284
9285 \family typewriter 
9286 ptl_sr_value_t
9287 \family default 
9288  
9289 \end_inset 
9290 </cell>
9291 <cell alignment="left" valignment="top" usebox="none">
9292 \begin_inset Text
9293
9294 \layout Standard
9295 \noindent 
9296 values in status registers 
9297 \end_inset 
9298 </cell>
9299 <cell alignment="right" valignment="top" usebox="none">
9300 \begin_inset Text
9301
9302 \layout Standard
9303
9304  
9305 \begin_inset LatexCommand \ref{sec:stat-type}
9306
9307 \end_inset 
9308
9309
9310 \end_inset 
9311 </cell>
9312 <cell alignment="left" valignment="top" usebox="none">
9313 \begin_inset Text
9314
9315 \layout Standard
9316 \noindent 
9317 PtlNIStatus 
9318 \end_inset 
9319 </cell>
9320 </row>
9321 <row>
9322 <cell alignment="right" valignment="top" usebox="none">
9323 \begin_inset Text
9324
9325 \layout Standard
9326
9327  
9328 \family typewriter 
9329 ptl_unlink_t 
9330 \end_inset 
9331 </cell>
9332 <cell alignment="left" valignment="top" usebox="none">
9333 \begin_inset Text
9334
9335 \layout Standard
9336 \noindent 
9337 unlink options 
9338 \end_inset 
9339 </cell>
9340 <cell alignment="right" valignment="top" usebox="none">
9341 \begin_inset Text
9342
9343 \layout Standard
9344
9345  
9346 \begin_inset LatexCommand \ref{sec:meattach}
9347
9348 \end_inset 
9349
9350
9351 \end_inset 
9352 </cell>
9353 <cell alignment="left" valignment="top" usebox="none">
9354 \begin_inset Text
9355
9356 \layout Standard
9357 \noindent 
9358 PtlMEAttach, PtlMEAttachAny, PtlMEInsert, PtlMDAttach 
9359 \end_inset 
9360 </cell>
9361 </row>
9362 </lyxtabular>
9363
9364 \end_inset 
9365
9366
9367 \end_inset 
9368
9369
9370 \layout Standard
9371
9372 Table\SpecialChar ~
9373
9374 \begin_inset LatexCommand \ref{tab:func}
9375
9376 \end_inset 
9377
9378  presents a summary of the functions defined by the Portals API.
9379  The first column in this table gives the name for the function, the second
9380  column gives a brief description of the operation implemented by the function,
9381  and the third column identifies the section where the function is defined.
9382 \layout Standard
9383
9384
9385 \begin_inset Float table
9386 placement htbp
9387 wide false
9388 collapsed false
9389
9390 \layout Caption
9391
9392 Functions Defined by the Portals 3.2 API
9393 \begin_inset LatexCommand \label{tab:func}
9394
9395 \end_inset 
9396
9397
9398 \layout Standard
9399
9400
9401 \begin_inset ERT
9402 status Collapsed
9403
9404 \layout Standard
9405
9406 \backslash 
9407 medskip  
9408 \end_inset 
9409
9410
9411 \layout Standard
9412 \align center 
9413
9414 \size small 
9415
9416 \begin_inset  Tabular
9417 <lyxtabular version="3" rows="24" columns="3">
9418 <features firstHeadEmpty="true">
9419 <column alignment="left" valignment="top" width="0pt">
9420 <column alignment="left" valignment="top" width="0pt">
9421 <column alignment="left" valignment="top" width="0pt">
9422 <row bottomline="true">
9423 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
9424 \begin_inset Text
9425
9426 \layout Standard
9427
9428 Name 
9429 \end_inset 
9430 </cell>
9431 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
9432 \begin_inset Text
9433
9434 \layout Standard
9435
9436  Operation 
9437 \end_inset 
9438 </cell>
9439 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
9440 \begin_inset Text
9441
9442 \layout Standard
9443
9444  Section 
9445 \end_inset 
9446 </cell>
9447 </row>
9448 <row>
9449 <cell alignment="left" valignment="top" usebox="none">
9450 \begin_inset Text
9451
9452 \layout Standard
9453
9454 PtlACEntry 
9455 \end_inset 
9456 </cell>
9457 <cell alignment="left" valignment="top" usebox="none">
9458 \begin_inset Text
9459
9460 \layout Standard
9461
9462  update an entry in an access control table 
9463 \end_inset 
9464 </cell>
9465 <cell alignment="left" valignment="top" usebox="none">
9466 \begin_inset Text
9467
9468 \layout Standard
9469
9470  
9471 \begin_inset LatexCommand \ref{sec:ac}
9472
9473 \end_inset 
9474
9475
9476 \end_inset 
9477 </cell>
9478 </row>
9479 <row>
9480 <cell alignment="left" valignment="top" usebox="none">
9481 \begin_inset Text
9482
9483 \layout Standard
9484
9485  PtlEQAlloc 
9486 \end_inset 
9487 </cell>
9488 <cell alignment="left" valignment="top" usebox="none">
9489 \begin_inset Text
9490
9491 \layout Standard
9492
9493  create an event queue 
9494 \end_inset 
9495 </cell>
9496 <cell alignment="left" valignment="top" usebox="none">
9497 \begin_inset Text
9498
9499 \layout Standard
9500
9501  
9502 \begin_inset LatexCommand \ref{sec:eq}
9503
9504 \end_inset 
9505
9506
9507 \end_inset 
9508 </cell>
9509 </row>
9510 <row>
9511 <cell alignment="left" valignment="top" usebox="none">
9512 \begin_inset Text
9513
9514 \layout Standard
9515
9516  PtlEQGet 
9517 \end_inset 
9518 </cell>
9519 <cell alignment="left" valignment="top" usebox="none">
9520 \begin_inset Text
9521
9522 \layout Standard
9523
9524  get the next event from an event queue 
9525 \end_inset 
9526 </cell>
9527 <cell alignment="left" valignment="top" usebox="none">
9528 \begin_inset Text
9529
9530 \layout Standard
9531
9532  
9533 \begin_inset LatexCommand \ref{sec:eq}
9534
9535 \end_inset 
9536
9537
9538 \end_inset 
9539 </cell>
9540 </row>
9541 <row>
9542 <cell alignment="left" valignment="top" usebox="none">
9543 \begin_inset Text
9544
9545 \layout Standard
9546
9547  PtlEQFree 
9548 \end_inset 
9549 </cell>
9550 <cell alignment="left" valignment="top" usebox="none">
9551 \begin_inset Text
9552
9553 \layout Standard
9554
9555  release the resources for an event queue 
9556 \end_inset 
9557 </cell>
9558 <cell alignment="left" valignment="top" usebox="none">
9559 \begin_inset Text
9560
9561 \layout Standard
9562
9563  
9564 \begin_inset LatexCommand \ref{sec:eq}
9565
9566 \end_inset 
9567
9568
9569 \end_inset 
9570 </cell>
9571 </row>
9572 <row>
9573 <cell alignment="left" valignment="top" usebox="none">
9574 \begin_inset Text
9575
9576 \layout Standard
9577
9578  PtlEQWait 
9579 \end_inset 
9580 </cell>
9581 <cell alignment="left" valignment="top" usebox="none">
9582 \begin_inset Text
9583
9584 \layout Standard
9585
9586  wait for a new event in an event queue 
9587 \end_inset 
9588 </cell>
9589 <cell alignment="left" valignment="top" usebox="none">
9590 \begin_inset Text
9591
9592 \layout Standard
9593
9594  
9595 \begin_inset LatexCommand \ref{sec:eq}
9596
9597 \end_inset 
9598
9599
9600 \end_inset 
9601 </cell>
9602 </row>
9603 <row>
9604 <cell alignment="left" valignment="top" usebox="none">
9605 \begin_inset Text
9606
9607 \layout Standard
9608
9609  PtlFini 
9610 \end_inset 
9611 </cell>
9612 <cell alignment="left" valignment="top" usebox="none">
9613 \begin_inset Text
9614
9615 \layout Standard
9616
9617  shutdown the Portals API 
9618 \end_inset 
9619 </cell>
9620 <cell alignment="left" valignment="top" usebox="none">
9621 \begin_inset Text
9622
9623 \layout Standard
9624
9625  
9626 \begin_inset LatexCommand \ref{sec:init}
9627
9628 \end_inset 
9629
9630
9631 \end_inset 
9632 </cell>
9633 </row>
9634 <row>
9635 <cell alignment="left" valignment="top" usebox="none">
9636 \begin_inset Text
9637
9638 \layout Standard
9639
9640  PtlGet 
9641 \end_inset 
9642 </cell>
9643 <cell alignment="left" valignment="top" usebox="none">
9644 \begin_inset Text
9645
9646 \layout Standard
9647
9648  perform a get operation 
9649 \end_inset 
9650 </cell>
9651 <cell alignment="left" valignment="top" usebox="none">
9652 \begin_inset Text
9653
9654 \layout Standard
9655
9656  
9657 \begin_inset LatexCommand \ref{sec:datamovement}
9658
9659 \end_inset 
9660
9661
9662 \end_inset 
9663 </cell>
9664 </row>
9665 <row>
9666 <cell alignment="left" valignment="top" usebox="none">
9667 \begin_inset Text
9668
9669 \layout Standard
9670
9671  PtlGetId 
9672 \end_inset 
9673 </cell>
9674 <cell alignment="left" valignment="top" usebox="none">
9675 \begin_inset Text
9676
9677 \layout Standard
9678
9679  get the id for the current process 
9680 \end_inset 
9681 </cell>
9682 <cell alignment="left" valignment="top" usebox="none">
9683 \begin_inset Text
9684
9685 \layout Standard
9686
9687  
9688 \begin_inset LatexCommand \ref{sec:pid}
9689
9690 \end_inset 
9691
9692
9693 \end_inset 
9694 </cell>
9695 </row>
9696 <row>
9697 <cell alignment="left" valignment="top" usebox="none">
9698 \begin_inset Text
9699
9700 \layout Standard
9701
9702  PtlInit 
9703 \end_inset 
9704 </cell>
9705 <cell alignment="left" valignment="top" usebox="none">
9706 \begin_inset Text
9707
9708 \layout Standard
9709
9710  initialize the Portals API 
9711 \end_inset 
9712 </cell>
9713 <cell alignment="left" valignment="top" usebox="none">
9714 \begin_inset Text
9715
9716 \layout Standard
9717
9718  
9719 \begin_inset LatexCommand \ref{sec:init}
9720
9721 \end_inset 
9722
9723
9724 \end_inset 
9725 </cell>
9726 </row>
9727 <row>
9728 <cell alignment="left" valignment="top" usebox="none">
9729 \begin_inset Text
9730
9731 \layout Standard
9732
9733  PtlMDAttach 
9734 \end_inset 
9735 </cell>
9736 <cell alignment="left" valignment="top" usebox="none">
9737 \begin_inset Text
9738
9739 \layout Standard
9740
9741  create a memory descriptor and attach it to a match entry 
9742 \end_inset 
9743 </cell>
9744 <cell alignment="left" valignment="top" usebox="none">
9745 \begin_inset Text
9746
9747 \layout Standard
9748
9749  
9750 \begin_inset LatexCommand \ref{sec:md}
9751
9752 \end_inset 
9753
9754
9755 \end_inset 
9756 </cell>
9757 </row>
9758 <row>
9759 <cell alignment="left" valignment="top" usebox="none">
9760 \begin_inset Text
9761
9762 \layout Standard
9763
9764  PtlMDBind 
9765 \end_inset 
9766 </cell>
9767 <cell alignment="left" valignment="top" usebox="none">
9768 \begin_inset Text
9769
9770 \layout Standard
9771
9772  create a free-floating memory descriptor 
9773 \end_inset 
9774 </cell>
9775 <cell alignment="left" valignment="top" usebox="none">
9776 \begin_inset Text
9777
9778 \layout Standard
9779
9780  
9781 \begin_inset LatexCommand \ref{sec:mdbind}
9782
9783 \end_inset 
9784
9785
9786 \end_inset 
9787 </cell>
9788 </row>
9789 <row>
9790 <cell alignment="left" valignment="top" usebox="none">
9791 \begin_inset Text
9792
9793 \layout Standard
9794
9795  PtlMDUnlink 
9796 \end_inset 
9797 </cell>
9798 <cell alignment="left" valignment="top" usebox="none">
9799 \begin_inset Text
9800
9801 \layout Standard
9802
9803  remove a memory descriptor from a list and release its resources 
9804 \end_inset 
9805 </cell>
9806 <cell alignment="left" valignment="top" usebox="none">
9807 \begin_inset Text
9808
9809 \layout Standard
9810
9811  
9812 \begin_inset LatexCommand \ref{sec:md}
9813
9814 \end_inset 
9815
9816
9817 \end_inset 
9818 </cell>
9819 </row>
9820 <row>
9821 <cell alignment="left" valignment="top" usebox="none">
9822 \begin_inset Text
9823
9824 \layout Standard
9825
9826  PtlMDUpdate 
9827 \end_inset 
9828 </cell>
9829 <cell alignment="left" valignment="top" usebox="none">
9830 \begin_inset Text
9831
9832 \layout Standard
9833
9834  update a memory descriptor 
9835 \end_inset 
9836 </cell>
9837 <cell alignment="left" valignment="top" usebox="none">
9838 \begin_inset Text
9839
9840 \layout Standard
9841
9842  
9843 \begin_inset LatexCommand \ref{sec:md}
9844
9845 \end_inset 
9846
9847
9848 \end_inset 
9849 </cell>
9850 </row>
9851 <row>
9852 <cell alignment="left" valignment="top" usebox="none">
9853 \begin_inset Text
9854
9855 \layout Standard
9856
9857  PtlMEAttach 
9858 \end_inset 
9859 </cell>
9860 <cell alignment="left" valignment="top" usebox="none">
9861 \begin_inset Text
9862
9863 \layout Standard
9864
9865 create a match entry and attach it to a Portal table 
9866 \end_inset 
9867 </cell>
9868 <cell alignment="left" valignment="top" usebox="none">
9869 \begin_inset Text
9870
9871 \layout Standard
9872
9873  
9874 \begin_inset LatexCommand \ref{sec:me}
9875
9876 \end_inset 
9877
9878
9879 \end_inset 
9880 </cell>
9881 </row>
9882 <row>
9883 <cell alignment="left" valignment="top" usebox="none">
9884 \begin_inset Text
9885
9886 \layout Standard
9887
9888 PtlMEAttachAny
9889 \end_inset 
9890 </cell>
9891 <cell alignment="left" valignment="top" usebox="none">
9892 \begin_inset Text
9893
9894 \layout Standard
9895
9896 create a match entry and attach it to a free Portal table entry
9897 \end_inset 
9898 </cell>
9899 <cell alignment="left" valignment="top" usebox="none">
9900 \begin_inset Text
9901
9902 \layout Standard
9903
9904
9905 \begin_inset LatexCommand \ref{sec:attachany}
9906
9907 \end_inset 
9908
9909
9910 \end_inset 
9911 </cell>
9912 </row>
9913 <row>
9914 <cell alignment="left" valignment="top" usebox="none">
9915 \begin_inset Text
9916
9917 \layout Standard
9918
9919  PtlMEInsert 
9920 \end_inset 
9921 </cell>
9922 <cell alignment="left" valignment="top" usebox="none">
9923 \begin_inset Text
9924
9925 \layout Standard
9926
9927  create a match entry and insert it in a list 
9928 \end_inset 
9929 </cell>
9930 <cell alignment="left" valignment="top" usebox="none">
9931 \begin_inset Text
9932
9933 \layout Standard
9934
9935  
9936 \begin_inset LatexCommand \ref{sec:me}
9937
9938 \end_inset 
9939
9940
9941 \end_inset 
9942 </cell>
9943 </row>
9944 <row>
9945 <cell alignment="left" valignment="top" usebox="none">
9946 \begin_inset Text
9947
9948 \layout Standard
9949
9950  PtlMEUnlink 
9951 \end_inset 
9952 </cell>
9953 <cell alignment="left" valignment="top" usebox="none">
9954 \begin_inset Text
9955
9956 \layout Standard
9957
9958  remove a match entry from a list and release its resources 
9959 \end_inset 
9960 </cell>
9961 <cell alignment="left" valignment="top" usebox="none">
9962 \begin_inset Text
9963
9964 \layout Standard
9965
9966  
9967 \begin_inset LatexCommand \ref{sec:me}
9968
9969 \end_inset 
9970
9971
9972 \end_inset 
9973 </cell>
9974 </row>
9975 <row>
9976 <cell alignment="left" valignment="top" usebox="none">
9977 \begin_inset Text
9978
9979 \layout Standard
9980
9981  PtlNIDist 
9982 \end_inset 
9983 </cell>
9984 <cell alignment="left" valignment="top" usebox="none">
9985 \begin_inset Text
9986
9987 \layout Standard
9988
9989  get the distance to another process 
9990 \end_inset 
9991 </cell>
9992 <cell alignment="left" valignment="top" usebox="none">
9993 \begin_inset Text
9994
9995 \layout Standard
9996
9997  
9998 \begin_inset LatexCommand \ref{sec:ni}
9999
10000 \end_inset 
10001
10002
10003 \end_inset 
10004 </cell>
10005 </row>
10006 <row>
10007 <cell alignment="left" valignment="top" usebox="none">
10008 \begin_inset Text
10009
10010 \layout Standard
10011
10012  PtlNIFini 
10013 \end_inset 
10014 </cell>
10015 <cell alignment="left" valignment="top" usebox="none">
10016 \begin_inset Text
10017
10018 \layout Standard
10019
10020  shutdown a network interface 
10021 \end_inset 
10022 </cell>
10023 <cell alignment="left" valignment="top" usebox="none">
10024 \begin_inset Text
10025
10026 \layout Standard
10027
10028  
10029 \begin_inset LatexCommand \ref{sec:ni}
10030
10031 \end_inset 
10032
10033
10034 \end_inset 
10035 </cell>
10036 </row>
10037 <row>
10038 <cell alignment="left" valignment="top" usebox="none">
10039 \begin_inset Text
10040
10041 \layout Standard
10042
10043  PtlNIHandle 
10044 \end_inset 
10045 </cell>
10046 <cell alignment="left" valignment="top" usebox="none">
10047 \begin_inset Text
10048
10049 \layout Standard
10050
10051  get the network interface handle for an object 
10052 \end_inset 
10053 </cell>
10054 <cell alignment="left" valignment="top" usebox="none">
10055 \begin_inset Text
10056
10057 \layout Standard
10058
10059  
10060 \begin_inset LatexCommand \ref{sec:ni}
10061
10062 \end_inset 
10063
10064
10065 \end_inset 
10066 </cell>
10067 </row>
10068 <row>
10069 <cell alignment="left" valignment="top" usebox="none">
10070 \begin_inset Text
10071
10072 \layout Standard
10073
10074  PtlNIInit 
10075 \end_inset 
10076 </cell>
10077 <cell alignment="left" valignment="top" usebox="none">
10078 \begin_inset Text
10079
10080 \layout Standard
10081
10082  initialize a network interface 
10083 \end_inset 
10084 </cell>
10085 <cell alignment="left" valignment="top" usebox="none">
10086 \begin_inset Text
10087
10088 \layout Standard
10089
10090  
10091 \begin_inset LatexCommand \ref{sec:ni}
10092
10093 \end_inset 
10094
10095
10096 \end_inset 
10097 </cell>
10098 </row>
10099 <row>
10100 <cell alignment="left" valignment="top" usebox="none">
10101 \begin_inset Text
10102
10103 \layout Standard
10104
10105  PtlNIStatus 
10106 \end_inset 
10107 </cell>
10108 <cell alignment="left" valignment="top" usebox="none">
10109 \begin_inset Text
10110
10111 \layout Standard
10112
10113  read a network interface status register 
10114 \end_inset 
10115 </cell>
10116 <cell alignment="left" valignment="top" usebox="none">
10117 \begin_inset Text
10118
10119 \layout Standard
10120
10121  
10122 \begin_inset LatexCommand \ref{sec:ni}
10123
10124 \end_inset 
10125
10126
10127 \end_inset 
10128 </cell>
10129 </row>
10130 <row>
10131 <cell alignment="left" valignment="top" usebox="none">
10132 \begin_inset Text
10133
10134 \layout Standard
10135
10136  PtlPut 
10137 \end_inset 
10138 </cell>
10139 <cell alignment="left" valignment="top" usebox="none">
10140 \begin_inset Text
10141
10142 \layout Standard
10143
10144  perform a put operation 
10145 \end_inset 
10146 </cell>
10147 <cell alignment="left" valignment="top" usebox="none">
10148 \begin_inset Text
10149
10150 \layout Standard
10151
10152  
10153 \begin_inset LatexCommand \ref{sec:datamovement}
10154
10155 \end_inset 
10156
10157
10158 \end_inset 
10159 </cell>
10160 </row>
10161 </lyxtabular>
10162
10163 \end_inset 
10164
10165
10166 \end_inset 
10167
10168
10169 \layout Standard
10170
10171 Table\SpecialChar ~
10172
10173 \begin_inset LatexCommand \ref{tab:retcodes}
10174
10175 \end_inset 
10176
10177  summarizes the return codes used by functions defined by the Portals API.
10178  All of these constants are integer values.
10179  The first column of this table gives the symbolic name for the constant,
10180  the second column gives a brief description of the value, and the third
10181  column identifies the functions that can return this value.
10182 \layout Standard
10183
10184
10185 \begin_inset Float table
10186 placement htbp
10187 wide false
10188 collapsed false
10189
10190 \layout Caption
10191
10192 Function Return Codes for the Portals 3.2 API
10193 \begin_inset LatexCommand \label{tab:retcodes}
10194
10195 \end_inset 
10196
10197
10198 \layout Standard
10199
10200
10201 \begin_inset ERT
10202 status Collapsed
10203
10204 \layout Standard
10205
10206 \backslash 
10207 medskip  
10208 \end_inset 
10209
10210
10211 \layout Standard
10212 \align center 
10213
10214 \size small 
10215
10216 \begin_inset  Tabular
10217 <lyxtabular version="3" rows="27" columns="3">
10218 <features>
10219 <column alignment="left" valignment="top" width="0pt">
10220 <column alignment="left" valignment="top" width="0pt">
10221 <column alignment="left" valignment="top" width="2.6in">
10222 <row bottomline="true">
10223 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10224 \begin_inset Text
10225
10226 \layout Standard
10227
10228
10229 \series bold 
10230 Name
10231 \end_inset 
10232 </cell>
10233 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
10234 \begin_inset Text
10235
10236 \layout Standard
10237
10238
10239 \series bold 
10240 Meaning 
10241 \end_inset 
10242 </cell>
10243 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10244 \begin_inset Text
10245
10246 \layout Standard
10247
10248  
10249 \series bold 
10250 Functions
10251 \series default 
10252  
10253 \end_inset 
10254 </cell>
10255 </row>
10256 <row>
10257 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10258 \begin_inset Text
10259
10260 \layout Standard
10261
10262
10263 \family typewriter 
10264 PTL_AC_INV_INDEX
10265 \family default 
10266  
10267 \end_inset 
10268 </cell>
10269 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
10270 \begin_inset Text
10271
10272 \layout Standard
10273
10274 invalid access control table index 
10275 \end_inset 
10276 </cell>
10277 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10278 \begin_inset Text
10279
10280 \layout Standard
10281 \noindent 
10282  PtlACEntry 
10283 \end_inset 
10284 </cell>
10285 </row>
10286 <row>
10287 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10288 \begin_inset Text
10289
10290 \layout Standard
10291
10292
10293 \family typewriter 
10294 PTL_EQ_DROPPED
10295 \family default 
10296  
10297 \end_inset 
10298 </cell>
10299 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
10300 \begin_inset Text
10301
10302 \layout Standard
10303
10304 at least one event has been dropped 
10305 \end_inset 
10306 </cell>
10307 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10308 \begin_inset Text
10309
10310 \layout Standard
10311 \noindent 
10312  PtlEQGet, PtlWait 
10313 \end_inset 
10314 </cell>
10315 </row>
10316 <row>
10317 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10318 \begin_inset Text
10319
10320 \layout Standard
10321
10322
10323 \family typewriter 
10324 PTL_EQ_EMPTY
10325 \end_inset 
10326 </cell>
10327 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
10328 \begin_inset Text
10329
10330 \layout Standard
10331
10332 no events available in an event queue 
10333 \end_inset 
10334 </cell>
10335 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10336 \begin_inset Text
10337
10338 \layout Standard
10339 \noindent 
10340  PtlEQGet 
10341 \end_inset 
10342 </cell>
10343 </row>
10344 <row>
10345 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10346 \begin_inset Text
10347
10348 \layout Standard
10349
10350
10351 \family typewriter 
10352 PTL_FAIL 
10353 \end_inset 
10354 </cell>
10355 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
10356 \begin_inset Text
10357
10358 \layout Standard
10359
10360 error during initialization or cleanup 
10361 \end_inset 
10362 </cell>
10363 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
10364 \begin_inset Text
10365
10366 \layout Standard
10367 \noindent 
10368  PtlInit, PtlFini 
10369 \end_inset 
10370 </cell>
10371 </row>
10372 <row>
10373 <cell alignment="right" valignment="top" usebox="none">
10374 \begin_inset Text
10375
10376 \layout Standard
10377
10378
10379 \family typewriter 
10380 PTL_ILL_MD
10381 \family default 
10382  
10383 \end_inset 
10384 </cell>
10385 <cell alignment="left" valignment="top" usebox="none">
10386 \begin_inset Text
10387
10388 \layout Standard
10389
10390 illegal memory descriptor values 
10391 \end_inset 
10392 </cell>
10393 <cell alignment="right" valignment="top" usebox="none">
10394 \begin_inset Text
10395
10396 \layout Standard
10397 \noindent 
10398 PtlMDAttach, PtlMDBind, PtlMDUpdate 
10399 \end_inset 
10400 </cell>
10401 </row>
10402 <row>
10403 <cell alignment="right" valignment="top" usebox="none">
10404 \begin_inset Text
10405
10406 \layout Standard
10407
10408
10409 \family typewriter 
10410 PTL_INIT_DUP 
10411 \end_inset 
10412 </cell>
10413 <cell alignment="left" valignment="top" usebox="none">
10414 \begin_inset Text
10415
10416 \layout Standard
10417
10418 duplicate initialization of an interface 
10419 \end_inset 
10420 </cell>
10421 <cell alignment="right" valignment="top" usebox="none">
10422 \begin_inset Text
10423
10424 \layout Standard
10425 \noindent 
10426 PtlNIInit 
10427 \end_inset 
10428 </cell>
10429 </row>
10430 <row>
10431 <cell alignment="right" valignment="top" usebox="none">
10432 \begin_inset Text
10433
10434 \layout Standard
10435
10436
10437 \family typewriter 
10438 PTL_INIT_INV
10439 \family default 
10440  
10441 \end_inset 
10442 </cell>
10443 <cell alignment="left" valignment="top" usebox="none">
10444 \begin_inset Text
10445
10446 \layout Standard
10447
10448 initialization of an invalid interface 
10449 \end_inset 
10450 </cell>
10451 <cell alignment="right" valignment="top" usebox="none">
10452 \begin_inset Text
10453
10454 \layout Standard
10455 \noindent 
10456 PtlNIInit 
10457 \end_inset 
10458 </cell>
10459 </row>
10460 <row>
10461 <cell alignment="right" valignment="top" usebox="none">
10462 \begin_inset Text
10463
10464 \layout Standard
10465
10466
10467 \family typewriter 
10468 PTL_INUSE
10469 \end_inset 
10470 </cell>
10471 <cell alignment="left" valignment="top" usebox="none">
10472 \begin_inset Text
10473
10474 \layout Standard
10475
10476 the ME already has an MD
10477 \end_inset 
10478 </cell>
10479 <cell alignment="right" valignment="top" usebox="none">
10480 \begin_inset Text
10481
10482 \layout Standard
10483 \noindent 
10484 PtlMDAttach
10485 \end_inset 
10486 </cell>
10487 </row>
10488 <row>
10489 <cell alignment="right" valignment="top" usebox="none">
10490 \begin_inset Text
10491
10492 \layout Standard
10493
10494
10495 \family typewriter 
10496 PTL_INV_ASIZE
10497 \family default 
10498  
10499 \end_inset 
10500 </cell>
10501 <cell alignment="left" valignment="top" usebox="none">
10502 \begin_inset Text
10503
10504 \layout Standard
10505
10506 invalid access control table size 
10507 \end_inset 
10508 </cell>
10509 <cell alignment="right" valignment="top" usebox="none">
10510 \begin_inset Text
10511
10512 \layout Standard
10513 \noindent 
10514 PtlNIInit 
10515 \end_inset 
10516 </cell>
10517 </row>
10518 <row>
10519 <cell alignment="right" valignment="top" usebox="none">
10520 \begin_inset Text
10521
10522 \layout Standard
10523
10524
10525 \family typewriter 
10526 PTL_INV_EQ
10527 \family default 
10528  
10529 \end_inset 
10530 </cell>
10531 <cell alignment="left" valignment="top" usebox="none">
10532 \begin_inset Text
10533
10534 \layout Standard
10535
10536 invalid event queue handle 
10537 \end_inset 
10538 </cell>
10539 <cell alignment="right" valignment="top" usebox="none">
10540 \begin_inset Text
10541
10542 \layout Standard
10543 \noindent 
10544 PtlMDUpdate, PtlEQFree, PtlEQGet 
10545 \end_inset 
10546 </cell>
10547 </row>
10548 <row>
10549 <cell alignment="right" valignment="top" usebox="none">
10550 \begin_inset Text
10551
10552 \layout Standard
10553
10554
10555 \family typewriter 
10556 PTL_INV_HANDLE 
10557 \end_inset 
10558 </cell>
10559 <cell alignment="left" valignment="top" usebox="none">
10560 \begin_inset Text
10561
10562 \layout Standard
10563
10564 invalid handle 
10565 \end_inset 
10566 </cell>
10567 <cell alignment="right" valignment="top" usebox="none">
10568 \begin_inset Text
10569
10570 \layout Standard
10571 \noindent 
10572 PtlNIHandle 
10573 \end_inset 
10574 </cell>
10575 </row>
10576 <row>
10577 <cell alignment="right" valignment="top" usebox="none">
10578 \begin_inset Text
10579
10580 \layout Standard
10581
10582
10583 \family typewriter 
10584 PTL_INV_MD 
10585 \end_inset 
10586 </cell>
10587 <cell alignment="left" valignment="top" usebox="none">
10588 \begin_inset Text
10589
10590 \layout Standard
10591
10592 invalid memory descriptor handle 
10593 \end_inset 
10594 </cell>
10595 <cell alignment="right" valignment="top" usebox="none">
10596 \begin_inset Text
10597
10598 \layout Standard
10599 \noindent 
10600 PtlMDUnlink, PtlMDUpdate 
10601 \end_inset 
10602 </cell>
10603 </row>
10604 <row>
10605 <cell alignment="right" valignment="top" usebox="none">
10606 \begin_inset Text
10607
10608 \layout Standard
10609
10610
10611 \family typewriter 
10612 PTL_INV_ME
10613 \family default 
10614  
10615 \end_inset 
10616 </cell>
10617 <cell alignment="left" valignment="top" usebox="none">
10618 \begin_inset Text
10619
10620 \layout Standard
10621
10622 invalid match entry handle 
10623 \end_inset 
10624 </cell>
10625 <cell alignment="right" valignment="top" usebox="none">
10626 \begin_inset Text
10627
10628 \layout Standard
10629 \noindent 
10630 PtlMDAttach 
10631 \end_inset 
10632 </cell>
10633 </row>
10634 <row>
10635 <cell alignment="right" valignment="top" usebox="none">
10636 \begin_inset Text
10637
10638 \layout Standard
10639
10640
10641 \family typewriter 
10642 PTL_INV_NI 
10643 \end_inset 
10644 </cell>
10645 <cell alignment="left" valignment="top" usebox="none">
10646 \begin_inset Text
10647
10648 \layout Standard
10649
10650 invalid network interface handle 
10651 \end_inset 
10652 </cell>
10653 <cell alignment="right" valignment="top" usebox="none">
10654 \begin_inset Text
10655
10656 \layout Standard
10657 \noindent 
10658 PtlNIDist, PtlNIFini, PtlMDBind, PtlEQAlloc 
10659 \end_inset 
10660 </cell>
10661 </row>
10662 <row>
10663 <cell alignment="right" valignment="top" usebox="none">
10664 \begin_inset Text
10665
10666 \layout Standard
10667
10668
10669 \family typewriter 
10670 PTL_INV_PROC 
10671 \end_inset 
10672 </cell>
10673 <cell alignment="left" valignment="top" usebox="none">
10674 \begin_inset Text
10675
10676 \layout Standard
10677
10678 invalid process identifier 
10679 \end_inset 
10680 </cell>
10681 <cell alignment="right" valignment="top" usebox="none">
10682 \begin_inset Text
10683
10684 \layout Standard
10685 \noindent 
10686 PtlNIInit, PtlNIDist, PtlMEAttach, PtlMEInsert, PtlACEntry, PtlPut, PtlGet
10687  
10688 \end_inset 
10689 </cell>
10690 </row>
10691 <row>
10692 <cell alignment="right" valignment="top" usebox="none">
10693 \begin_inset Text
10694
10695 \layout Standard
10696
10697
10698 \family typewriter 
10699 PTL_INV_PTINDEX
10700 \family default 
10701  
10702 \end_inset 
10703 </cell>
10704 <cell alignment="left" valignment="top" usebox="none">
10705 \begin_inset Text
10706
10707 \layout Standard
10708
10709 invalid Portal table index 
10710 \end_inset 
10711 </cell>
10712 <cell alignment="right" valignment="top" usebox="none">
10713 \begin_inset Text
10714
10715 \layout Standard
10716 \noindent 
10717  PtlMEAttach 
10718 \end_inset 
10719 </cell>
10720 </row>
10721 <row>
10722 <cell alignment="right" valignment="top" usebox="none">
10723 \begin_inset Text
10724
10725 \layout Standard
10726
10727
10728 \family typewriter 
10729 PTL_INV_REG 
10730 \end_inset 
10731 </cell>
10732 <cell alignment="left" valignment="top" usebox="none">
10733 \begin_inset Text
10734
10735 \layout Standard
10736
10737 invalid status register 
10738 \end_inset 
10739 </cell>
10740 <cell alignment="right" valignment="top" usebox="none">
10741 \begin_inset Text
10742
10743 \layout Standard
10744 \noindent 
10745  PtlNIStatus 
10746 \end_inset 
10747 </cell>
10748 </row>
10749 <row>
10750 <cell alignment="right" valignment="top" usebox="none">
10751 \begin_inset Text
10752
10753 \layout Standard
10754
10755
10756 \family typewriter 
10757 PTL_INV_SR_INDX 
10758 \end_inset 
10759 </cell>
10760 <cell alignment="left" valignment="top" usebox="none">
10761 \begin_inset Text
10762
10763 \layout Standard
10764
10765 invalid status register index 
10766 \end_inset 
10767 </cell>
10768 <cell alignment="right" valignment="top" usebox="none">
10769 \begin_inset Text
10770
10771 \layout Standard
10772 \noindent 
10773  PtlNIStatus 
10774 \end_inset 
10775 </cell>
10776 </row>
10777 <row>
10778 <cell alignment="right" valignment="top" usebox="none">
10779 \begin_inset Text
10780
10781 \layout Standard
10782
10783
10784 \family typewriter 
10785 PTL_ML_TOOLONG 
10786 \end_inset 
10787 </cell>
10788 <cell alignment="left" valignment="top" usebox="none">
10789 \begin_inset Text
10790
10791 \layout Standard
10792
10793 match list too long 
10794 \end_inset 
10795 </cell>
10796 <cell alignment="right" valignment="top" usebox="none">
10797 \begin_inset Text
10798
10799 \layout Standard
10800 \noindent 
10801  PtlMEAttach, PtlMEInsert 
10802 \end_inset 
10803 </cell>
10804 </row>
10805 <row>
10806 <cell alignment="right" valignment="top" usebox="none">
10807 \begin_inset Text
10808
10809 \layout Standard
10810
10811
10812 \family typewriter 
10813 PTL_MD_INUSE
10814 \end_inset 
10815 </cell>
10816 <cell alignment="left" valignment="top" usebox="none">
10817 \begin_inset Text
10818
10819 \layout Standard
10820
10821 MD has pending operations
10822 \end_inset 
10823 </cell>
10824 <cell alignment="right" valignment="top" usebox="none">
10825 \begin_inset Text
10826
10827 \layout Standard
10828
10829 PtlMDUnlink
10830 \end_inset 
10831 </cell>
10832 </row>
10833 <row>
10834 <cell alignment="right" valignment="top" usebox="none">
10835 \begin_inset Text
10836
10837 \layout Standard
10838
10839
10840 \family typewriter 
10841 PTL_NOINIT 
10842 \end_inset 
10843 </cell>
10844 <cell alignment="left" valignment="top" usebox="none">
10845 \begin_inset Text
10846
10847 \layout Standard
10848
10849 uninitialized API 
10850 \end_inset 
10851 </cell>
10852 <cell alignment="right" valignment="top" usebox="none">
10853 \begin_inset Text
10854
10855 \layout Standard
10856 \noindent 
10857  
10858 \emph on 
10859 all
10860 \emph default 
10861 , except PtlInit 
10862 \end_inset 
10863 </cell>
10864 </row>
10865 <row>
10866 <cell alignment="right" valignment="top" usebox="none">
10867 \begin_inset Text
10868
10869 \layout Standard
10870
10871
10872 \family typewriter 
10873 PTL_NOSPACE
10874 \family default 
10875  
10876 \end_inset 
10877 </cell>
10878 <cell alignment="left" valignment="top" usebox="none">
10879 \begin_inset Text
10880
10881 \layout Standard
10882
10883 insufficient memory 
10884 \end_inset 
10885 </cell>
10886 <cell alignment="right" valignment="top" usebox="none">
10887 \begin_inset Text
10888
10889 \layout Standard
10890 \noindent 
10891 PtlNIInit, PtlMDAttach, PtlMDBind, PtlEQAlloc, PtlMEAttach, PtlMEInsert
10892  
10893 \end_inset 
10894 </cell>
10895 </row>
10896 <row>
10897 <cell alignment="right" valignment="top" usebox="none">
10898 \begin_inset Text
10899
10900 \layout Standard
10901
10902  
10903 \family typewriter 
10904 PTL_NOUPDATE
10905 \family default 
10906  
10907 \end_inset 
10908 </cell>
10909 <cell alignment="left" valignment="top" usebox="none">
10910 \begin_inset Text
10911
10912 \layout Standard
10913
10914  no update was performed 
10915 \end_inset 
10916 </cell>
10917 <cell alignment="right" valignment="top" usebox="none">
10918 \begin_inset Text
10919
10920 \layout Standard
10921 \noindent 
10922  PtlMDUpdate 
10923 \end_inset 
10924 </cell>
10925 </row>
10926 <row>
10927 <cell alignment="right" valignment="top" usebox="none">
10928 \begin_inset Text
10929
10930 \layout Standard
10931
10932
10933 \family typewriter 
10934 PTL_PT_FULL
10935 \end_inset 
10936 </cell>
10937 <cell alignment="left" valignment="top" usebox="none">
10938 \begin_inset Text
10939
10940 \layout Standard
10941
10942 Portal table is full
10943 \end_inset 
10944 </cell>
10945 <cell alignment="right" valignment="top" usebox="none">
10946 \begin_inset Text
10947
10948 \layout Standard
10949
10950 PtlMEAttachAny
10951 \end_inset 
10952 </cell>
10953 </row>
10954 <row>
10955 <cell alignment="right" valignment="top" usebox="none">
10956 \begin_inset Text
10957
10958 \layout Standard
10959
10960
10961 \family typewriter 
10962 PTL_OK 
10963 \end_inset 
10964 </cell>
10965 <cell alignment="left" valignment="top" usebox="none">
10966 \begin_inset Text
10967
10968 \layout Standard
10969
10970  success 
10971 \end_inset 
10972 </cell>
10973 <cell alignment="right" valignment="top" usebox="none">
10974 \begin_inset Text
10975
10976 \layout Standard
10977 \noindent 
10978  
10979 \emph on 
10980 all
10981 \end_inset 
10982 </cell>
10983 </row>
10984 <row>
10985 <cell alignment="right" valignment="top" usebox="none">
10986 \begin_inset Text
10987
10988 \layout Standard
10989
10990
10991 \family typewriter 
10992 PTL_SEGV 
10993 \end_inset 
10994 </cell>
10995 <cell alignment="left" valignment="top" usebox="none">
10996 \begin_inset Text
10997
10998 \layout Standard
10999
11000 addressing violation 
11001 \end_inset 
11002 </cell>
11003 <cell alignment="left" valignment="top" usebox="none">
11004 \begin_inset Text
11005
11006 \layout Standard
11007 \noindent 
11008 PtlNIInit, PtlNIStatus, PtlNIDist, PtlNIHandle, PtlMDBind, PtlMDUpdate,
11009  PtlEQAlloc, PtlEQGet, PtlEQWait 
11010 \end_inset 
11011 </cell>
11012 </row>
11013 </lyxtabular>
11014
11015 \end_inset 
11016
11017
11018 \end_inset 
11019
11020
11021 \layout Standard
11022
11023 Table\SpecialChar ~
11024
11025 \begin_inset LatexCommand \ref{tab:oconsts}
11026
11027 \end_inset 
11028
11029  summarizes the remaining constant values introduced by the Portals API.
11030  The first column in this table presents the symbolic name for the constant,
11031  the second column gives a brief description of the value, the third column
11032  identifies the type for the value, and the fourth column identifies the
11033  sections in which the value is mentioned.
11034 \layout Standard
11035
11036
11037 \begin_inset Float table
11038 placement htbp
11039 wide false
11040 collapsed false
11041
11042 \layout Caption
11043
11044 Other Constants Defined by the Portals 3.2 API
11045 \begin_inset LatexCommand \label{tab:oconsts}
11046
11047 \end_inset 
11048
11049
11050 \layout Standard
11051
11052
11053 \begin_inset ERT
11054 status Collapsed
11055
11056 \layout Standard
11057
11058 \backslash 
11059 medskip  
11060 \end_inset 
11061
11062
11063 \layout Standard
11064 \align center 
11065
11066 \size small 
11067
11068 \begin_inset  Tabular
11069 <lyxtabular version="3" rows="36" columns="5">
11070 <features>
11071 <column alignment="left" valignment="top" width="0pt">
11072 <column alignment="left" valignment="top" width="0pt">
11073 <column alignment="left" valignment="top" width="0pt">
11074 <column alignment="left" valignment="top" width="0pt">
11075 <column alignment="left" valignment="top" width="0pt">
11076 <row bottomline="true">
11077 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11078 \begin_inset Text
11079
11080 \layout Standard
11081
11082
11083 \series bold 
11084 Name
11085 \end_inset 
11086 </cell>
11087 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11088 \begin_inset Text
11089
11090 \layout Standard
11091
11092
11093 \series bold 
11094 Meaning 
11095 \end_inset 
11096 </cell>
11097 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11098 \begin_inset Text
11099
11100 \layout Standard
11101
11102
11103 \series bold 
11104 Base type
11105 \end_inset 
11106 </cell>
11107 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11108 \begin_inset Text
11109
11110 \layout Standard
11111
11112
11113 \series bold 
11114 Intr.
11115 \end_inset 
11116 </cell>
11117 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11118 \begin_inset Text
11119
11120 \layout Standard
11121
11122
11123 \series bold 
11124 Ref.
11125 \end_inset 
11126 </cell>
11127 </row>
11128 <row>
11129 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11130 \begin_inset Text
11131
11132 \layout Standard
11133
11134
11135 \family typewriter 
11136 PTL_ACK_REQ
11137 \family default 
11138  
11139 \end_inset 
11140 </cell>
11141 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11142 \begin_inset Text
11143
11144 \layout Standard
11145
11146 request an acknowledgement 
11147 \end_inset 
11148 </cell>
11149 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11150 \begin_inset Text
11151
11152 \layout Standard
11153
11154
11155 \family typewriter 
11156 ptl_ack_req_t 
11157 \end_inset 
11158 </cell>
11159 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11160 \begin_inset Text
11161
11162 \layout Standard
11163
11164  
11165 \begin_inset LatexCommand \ref{sec:put}
11166
11167 \end_inset 
11168
11169
11170 \end_inset 
11171 </cell>
11172 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11173 \begin_inset Text
11174
11175 \layout Standard
11176
11177 \end_inset 
11178 </cell>
11179 </row>
11180 <row>
11181 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11182 \begin_inset Text
11183
11184 \layout Standard
11185
11186
11187 \family typewriter 
11188 PTL_EQ_NONE 
11189 \end_inset 
11190 </cell>
11191 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11192 \begin_inset Text
11193
11194 \layout Standard
11195
11196 a NULL event queue handle 
11197 \end_inset 
11198 </cell>
11199 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
11200 \begin_inset Text
11201
11202 \layout Standard
11203
11204
11205 \family typewriter 
11206 ptl_handle_eq_t 
11207 \end_inset 
11208 </cell>
11209 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11210 \begin_inset Text
11211
11212 \layout Standard
11213
11214  
11215 \begin_inset LatexCommand \ref{sec:handle-type}
11216
11217 \end_inset 
11218
11219
11220 \end_inset 
11221 </cell>
11222 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
11223 \begin_inset Text
11224
11225 \layout Standard
11226
11227  
11228 \begin_inset LatexCommand \ref{sec:md}
11229
11230 \end_inset 
11231
11232
11233 \begin_inset LatexCommand \ref{sec:mdupdate}
11234
11235 \end_inset 
11236
11237
11238 \end_inset 
11239 </cell>
11240 </row>
11241 <row>
11242 <cell alignment="right" valignment="top" usebox="none">
11243 \begin_inset Text
11244
11245 \layout Standard
11246
11247
11248 \family typewriter 
11249 PTL_EVENT_GET_START
11250 \end_inset 
11251 </cell>
11252 <cell alignment="left" valignment="top" usebox="none">
11253 \begin_inset Text
11254
11255 \layout Standard
11256
11257 get event start
11258 \end_inset 
11259 </cell>
11260 <cell alignment="right" valignment="top" usebox="none">
11261 \begin_inset Text
11262
11263 \layout Standard
11264
11265
11266 \family typewriter 
11267 ptl_event_kind_t 
11268 \end_inset 
11269 </cell>
11270 <cell alignment="left" valignment="top" usebox="none">
11271 \begin_inset Text
11272
11273 \layout Standard
11274
11275  
11276 \begin_inset LatexCommand \ref{sec:ek-type}
11277
11278 \end_inset 
11279
11280
11281 \end_inset 
11282 </cell>
11283 <cell alignment="left" valignment="top" usebox="none">
11284 \begin_inset Text
11285
11286 \layout Standard
11287
11288
11289 \begin_inset LatexCommand \ref{sec:get}
11290
11291 \end_inset 
11292
11293
11294 \end_inset 
11295 </cell>
11296 </row>
11297 <row>
11298 <cell alignment="right" valignment="top" usebox="none">
11299 \begin_inset Text
11300
11301 \layout Standard
11302
11303
11304 \family typewriter 
11305 PTL_EVENT_GET_END
11306 \end_inset 
11307 </cell>
11308 <cell alignment="left" valignment="top" usebox="none">
11309 \begin_inset Text
11310
11311 \layout Standard
11312
11313 get event end
11314 \end_inset 
11315 </cell>
11316 <cell alignment="right" valignment="top" usebox="none">
11317 \begin_inset Text
11318
11319 \layout Standard
11320
11321
11322 \family typewriter 
11323 ptl_event_kind_t 
11324 \end_inset 
11325 </cell>
11326 <cell alignment="left" valignment="top" usebox="none">
11327 \begin_inset Text
11328
11329 \layout Standard
11330
11331
11332 \begin_inset LatexCommand \ref{sec:ek-type}
11333
11334 \end_inset 
11335
11336
11337 \end_inset 
11338 </cell>
11339 <cell alignment="left" valignment="top" usebox="none">
11340 \begin_inset Text
11341
11342 \layout Standard
11343
11344
11345 \begin_inset LatexCommand \ref{sec:get}
11346
11347 \end_inset 
11348
11349
11350 \end_inset 
11351 </cell>
11352 </row>
11353 <row>
11354 <cell alignment="right" valignment="top" usebox="none">
11355 \begin_inset Text
11356
11357 \layout Standard
11358
11359
11360 \family typewriter 
11361 PTL_EVENT_GET_FAIL
11362 \end_inset 
11363 </cell>
11364 <cell alignment="left" valignment="top" usebox="none">
11365 \begin_inset Text
11366
11367 \layout Standard
11368
11369 get event fail
11370 \end_inset 
11371 </cell>
11372 <cell alignment="right" valignment="top" usebox="none">
11373 \begin_inset Text
11374
11375 \layout Standard
11376
11377
11378 \family typewriter 
11379 ptl_event_kind_t 
11380 \end_inset 
11381 </cell>
11382 <cell alignment="left" valignment="top" usebox="none">
11383 \begin_inset Text
11384
11385 \layout Standard
11386
11387
11388 \begin_inset LatexCommand \ref{sec:ek-type}
11389
11390 \end_inset 
11391
11392
11393 \end_inset 
11394 </cell>
11395 <cell alignment="left" valignment="top" usebox="none">
11396 \begin_inset Text
11397
11398 \layout Standard
11399
11400
11401 \begin_inset LatexCommand \ref{sec:get}
11402
11403 \end_inset 
11404
11405
11406 \end_inset 
11407 </cell>
11408 </row>
11409 <row>
11410 <cell alignment="right" valignment="top" usebox="none">
11411 \begin_inset Text
11412
11413 \layout Standard
11414
11415
11416 \family typewriter 
11417 PTL_EVENT_PUT_START
11418 \end_inset 
11419 </cell>
11420 <cell alignment="left" valignment="top" usebox="none">
11421 \begin_inset Text
11422
11423 \layout Standard
11424
11425 put event start
11426 \end_inset 
11427 </cell>
11428 <cell alignment="right" valignment="top" usebox="none">
11429 \begin_inset Text
11430
11431 \layout Standard
11432
11433
11434 \family typewriter 
11435 ptl_event_kind_t 
11436 \end_inset 
11437 </cell>
11438 <cell alignment="left" valignment="top" usebox="none">
11439 \begin_inset Text
11440
11441 \layout Standard
11442
11443  
11444 \begin_inset LatexCommand \ref{sec:ek-type}
11445
11446 \end_inset 
11447
11448
11449 \end_inset 
11450 </cell>
11451 <cell alignment="left" valignment="top" usebox="none">
11452 \begin_inset Text
11453
11454 \layout Standard
11455
11456
11457 \begin_inset LatexCommand \ref{sec:put}
11458
11459 \end_inset 
11460
11461
11462 \end_inset 
11463 </cell>
11464 </row>
11465 <row>
11466 <cell alignment="right" valignment="top" usebox="none">
11467 \begin_inset Text
11468
11469 \layout Standard
11470
11471
11472 \family typewriter 
11473 PTL_EVENT_PUT_END
11474 \end_inset 
11475 </cell>
11476 <cell alignment="left" valignment="top" usebox="none">
11477 \begin_inset Text
11478
11479 \layout Standard
11480
11481 put event end
11482 \end_inset 
11483 </cell>
11484 <cell alignment="right" valignment="top" usebox="none">
11485 \begin_inset Text
11486
11487 \layout Standard
11488
11489
11490 \family typewriter 
11491 ptl_event_kind_t 
11492 \end_inset 
11493 </cell>
11494 <cell alignment="left" valignment="top" usebox="none">
11495 \begin_inset Text
11496
11497 \layout Standard
11498
11499
11500 \begin_inset LatexCommand \ref{sec:ek-type}
11501
11502 \end_inset 
11503
11504
11505 \end_inset 
11506 </cell>
11507 <cell alignment="left" valignment="top" usebox="none">
11508 \begin_inset Text
11509
11510 \layout Standard
11511
11512
11513 \begin_inset LatexCommand \ref{sec:put}
11514
11515 \end_inset 
11516
11517
11518 \end_inset 
11519 </cell>
11520 </row>
11521 <row>
11522 <cell alignment="right" valignment="top" usebox="none">
11523 \begin_inset Text
11524
11525 \layout Standard
11526
11527
11528 \family typewriter 
11529 PTL_EVENT_PUT_FAIL
11530 \end_inset 
11531 </cell>
11532 <cell alignment="left" valignment="top" usebox="none">
11533 \begin_inset Text
11534
11535 \layout Standard
11536
11537 put event fail
11538 \end_inset 
11539 </cell>
11540 <cell alignment="right" valignment="top" usebox="none">
11541 \begin_inset Text
11542
11543 \layout Standard
11544
11545
11546 \family typewriter 
11547 ptl_event_kind_t 
11548 \end_inset 
11549 </cell>
11550 <cell alignment="left" valignment="top" usebox="none">
11551 \begin_inset Text
11552
11553 \layout Standard
11554
11555
11556 \begin_inset LatexCommand \ref{sec:ek-type}
11557
11558 \end_inset 
11559
11560
11561 \end_inset 
11562 </cell>
11563 <cell alignment="left" valignment="top" usebox="none">
11564 \begin_inset Text
11565
11566 \layout Standard
11567
11568
11569 \begin_inset LatexCommand \ref{sec:put}
11570
11571 \end_inset 
11572
11573
11574 \end_inset 
11575 </cell>
11576 </row>
11577 <row>
11578 <cell alignment="right" valignment="top" usebox="none">
11579 \begin_inset Text
11580
11581 \layout Standard
11582
11583
11584 \family typewriter 
11585 PTL_EVENT_REPLY_START
11586 \end_inset 
11587 </cell>
11588 <cell alignment="left" valignment="top" usebox="none">
11589 \begin_inset Text
11590
11591 \layout Standard
11592
11593 reply event start
11594 \end_inset 
11595 </cell>
11596 <cell alignment="right" valignment="top" usebox="none">
11597 \begin_inset Text
11598
11599 \layout Standard
11600
11601
11602 \family typewriter 
11603 ptl_event_kind_t 
11604 \end_inset 
11605 </cell>
11606 <cell alignment="left" valignment="top" usebox="none">
11607 \begin_inset Text
11608
11609 \layout Standard
11610
11611  
11612 \begin_inset LatexCommand \ref{sec:ek-type}
11613
11614 \end_inset 
11615
11616
11617 \end_inset 
11618 </cell>
11619 <cell alignment="left" valignment="top" usebox="none">
11620 \begin_inset Text
11621
11622 \layout Standard
11623
11624  
11625 \begin_inset LatexCommand \ref{sec:get}
11626
11627 \end_inset 
11628
11629
11630 \end_inset 
11631 </cell>
11632 </row>
11633 <row>
11634 <cell alignment="right" valignment="top" usebox="none">
11635 \begin_inset Text
11636
11637 \layout Standard
11638
11639
11640 \family typewriter 
11641 PTL_EVENT_REPLY_END
11642 \end_inset 
11643 </cell>
11644 <cell alignment="left" valignment="top" usebox="none">
11645 \begin_inset Text
11646
11647 \layout Standard
11648
11649 reply event end
11650 \end_inset 
11651 </cell>
11652 <cell alignment="right" valignment="top" usebox="none">
11653 \begin_inset Text
11654
11655 \layout Standard
11656
11657
11658 \family typewriter 
11659 ptl_event_kind_t 
11660 \end_inset 
11661 </cell>
11662 <cell alignment="left" valignment="top" usebox="none">
11663 \begin_inset Text
11664
11665 \layout Standard
11666
11667
11668 \begin_inset LatexCommand \ref{sec:ek-type}
11669
11670 \end_inset 
11671
11672
11673 \end_inset 
11674 </cell>
11675 <cell alignment="left" valignment="top" usebox="none">
11676 \begin_inset Text
11677
11678 \layout Standard
11679
11680
11681 \begin_inset LatexCommand \ref{sec:get}
11682
11683 \end_inset 
11684
11685
11686 \end_inset 
11687 </cell>
11688 </row>
11689 <row>
11690 <cell alignment="right" valignment="top" usebox="none">
11691 \begin_inset Text
11692
11693 \layout Standard
11694
11695
11696 \family typewriter 
11697 PTL_EVENT_REPLY_FAIL
11698 \end_inset 
11699 </cell>
11700 <cell alignment="left" valignment="top" usebox="none">
11701 \begin_inset Text
11702
11703 \layout Standard
11704
11705 reply event fail
11706 \end_inset 
11707 </cell>
11708 <cell alignment="right" valignment="top" usebox="none">
11709 \begin_inset Text
11710
11711 \layout Standard
11712
11713
11714 \family typewriter 
11715 ptl_event_kind_t 
11716 \end_inset 
11717 </cell>
11718 <cell alignment="left" valignment="top" usebox="none">
11719 \begin_inset Text
11720
11721 \layout Standard
11722
11723
11724 \begin_inset LatexCommand \ref{sec:ek-type}
11725
11726 \end_inset 
11727
11728
11729 \end_inset 
11730 </cell>
11731 <cell alignment="left" valignment="top" usebox="none">
11732 \begin_inset Text
11733
11734 \layout Standard
11735
11736
11737 \begin_inset LatexCommand \ref{sec:get}
11738
11739 \end_inset 
11740
11741
11742 \end_inset 
11743 </cell>
11744 </row>
11745 <row>
11746 <cell alignment="right" valignment="top" usebox="none">
11747 \begin_inset Text
11748
11749 \layout Standard
11750
11751
11752 \family typewriter 
11753 PTL_EVENT_ACK_START
11754 \end_inset 
11755 </cell>
11756 <cell alignment="left" valignment="top" usebox="none">
11757 \begin_inset Text
11758
11759 \layout Standard
11760
11761 acknowledgement event start
11762 \end_inset 
11763 </cell>
11764 <cell alignment="right" valignment="top" usebox="none">
11765 \begin_inset Text
11766
11767 \layout Standard
11768
11769
11770 \family typewriter 
11771 ptl_event_kind_t 
11772 \end_inset 
11773 </cell>
11774 <cell alignment="left" valignment="top" usebox="none">
11775 \begin_inset Text
11776
11777 \layout Standard
11778
11779  
11780 \begin_inset LatexCommand \ref{sec:ek-type}
11781
11782 \end_inset 
11783
11784
11785 \end_inset 
11786 </cell>
11787 <cell alignment="left" valignment="top" usebox="none">
11788 \begin_inset Text
11789
11790 \layout Standard
11791
11792  
11793 \begin_inset LatexCommand \ref{sec:put}
11794
11795 \end_inset 
11796
11797
11798 \end_inset 
11799 </cell>
11800 </row>
11801 <row>
11802 <cell alignment="right" valignment="top" usebox="none">
11803 \begin_inset Text
11804
11805 \layout Standard
11806
11807
11808 \family typewriter 
11809 PTL_EVENT_ACK_END
11810 \end_inset 
11811 </cell>
11812 <cell alignment="left" valignment="top" usebox="none">
11813 \begin_inset Text
11814
11815 \layout Standard
11816
11817 acknowledgement event end
11818 \end_inset 
11819 </cell>
11820 <cell alignment="right" valignment="top" usebox="none">
11821 \begin_inset Text
11822
11823 \layout Standard
11824
11825
11826 \family typewriter 
11827 ptl_event_kind_t 
11828 \end_inset 
11829 </cell>
11830 <cell alignment="left" valignment="top" usebox="none">
11831 \begin_inset Text
11832
11833 \layout Standard
11834
11835
11836 \begin_inset LatexCommand \ref{sec:ek-type}
11837
11838 \end_inset 
11839
11840
11841 \end_inset 
11842 </cell>
11843 <cell alignment="left" valignment="top" usebox="none">
11844 \begin_inset Text
11845
11846 \layout Standard
11847
11848
11849 \begin_inset LatexCommand \ref{sec:put}
11850
11851 \end_inset 
11852
11853
11854 \end_inset 
11855 </cell>
11856 </row>
11857 <row>
11858 <cell alignment="right" valignment="top" usebox="none">
11859 \begin_inset Text
11860
11861 \layout Standard
11862
11863
11864 \family typewriter 
11865 PTL_EVENT_ACK_FAIL
11866 \end_inset 
11867 </cell>
11868 <cell alignment="left" valignment="top" usebox="none">
11869 \begin_inset Text
11870
11871 \layout Standard
11872
11873 acknowledgement event fail
11874 \end_inset 
11875 </cell>
11876 <cell alignment="right" valignment="top" usebox="none">
11877 \begin_inset Text
11878
11879 \layout Standard
11880
11881
11882 \family typewriter 
11883 ptl_event_kind_t 
11884 \end_inset 
11885 </cell>
11886 <cell alignment="left" valignment="top" usebox="none">
11887 \begin_inset Text
11888
11889 \layout Standard
11890
11891
11892 \begin_inset LatexCommand \ref{sec:ek-type}
11893
11894 \end_inset 
11895
11896
11897 \end_inset 
11898 </cell>
11899 <cell alignment="left" valignment="top" usebox="none">
11900 \begin_inset Text
11901
11902 \layout Standard
11903
11904
11905 \begin_inset LatexCommand \ref{sec:put}
11906
11907 \end_inset 
11908
11909
11910 \end_inset 
11911 </cell>
11912 </row>
11913 <row>
11914 <cell alignment="right" valignment="top" usebox="none">
11915 \begin_inset Text
11916
11917 \layout Standard
11918
11919
11920 \family typewriter 
11921 PTL_EVENT_SEND_START
11922 \end_inset 
11923 </cell>
11924 <cell alignment="left" valignment="top" usebox="none">
11925 \begin_inset Text
11926
11927 \layout Standard
11928
11929 send event start
11930 \end_inset 
11931 </cell>
11932 <cell alignment="right" valignment="top" usebox="none">
11933 \begin_inset Text
11934
11935 \layout Standard
11936
11937
11938 \family typewriter 
11939 ptl_event_kind_t 
11940 \end_inset 
11941 </cell>
11942 <cell alignment="left" valignment="top" usebox="none">
11943 \begin_inset Text
11944
11945 \layout Standard
11946
11947  
11948 \begin_inset LatexCommand \ref{sec:ek-type}
11949
11950 \end_inset 
11951
11952
11953 \end_inset 
11954 </cell>
11955 <cell alignment="left" valignment="top" usebox="none">
11956 \begin_inset Text
11957
11958 \layout Standard
11959
11960  
11961 \begin_inset LatexCommand \ref{sec:put}
11962
11963 \end_inset 
11964
11965
11966 \end_inset 
11967 </cell>
11968 </row>
11969 <row>
11970 <cell alignment="right" valignment="top" usebox="none">
11971 \begin_inset Text
11972
11973 \layout Standard
11974
11975
11976 \family typewriter 
11977 PTL_EVENT_SEND_END
11978 \end_inset 
11979 </cell>
11980 <cell alignment="left" valignment="top" usebox="none">
11981 \begin_inset Text
11982
11983 \layout Standard
11984
11985 send event end
11986 \end_inset 
11987 </cell>
11988 <cell alignment="right" valignment="top" usebox="none">
11989 \begin_inset Text
11990
11991 \layout Standard
11992
11993
11994 \family typewriter 
11995 ptl_event_kind_t 
11996 \end_inset 
11997 </cell>
11998 <cell alignment="left" valignment="top" usebox="none">
11999 \begin_inset Text
12000
12001 \layout Standard
12002
12003
12004 \begin_inset LatexCommand \ref{sec:ek-type}
12005
12006 \end_inset 
12007
12008
12009 \end_inset 
12010 </cell>
12011 <cell alignment="left" valignment="top" usebox="none">
12012 \begin_inset Text
12013
12014 \layout Standard
12015
12016
12017 \begin_inset LatexCommand \ref{sec:put}
12018
12019 \end_inset 
12020
12021
12022 \end_inset 
12023 </cell>
12024 </row>
12025 <row>
12026 <cell alignment="right" valignment="top" usebox="none">
12027 \begin_inset Text
12028
12029 \layout Standard
12030
12031
12032 \family typewriter 
12033 PTL_EVENT_SEND_FAIL
12034 \end_inset 
12035 </cell>
12036 <cell alignment="left" valignment="top" usebox="none">
12037 \begin_inset Text
12038
12039 \layout Standard
12040
12041 send event fail
12042 \end_inset 
12043 </cell>
12044 <cell alignment="right" valignment="top" usebox="none">
12045 \begin_inset Text
12046
12047 \layout Standard
12048
12049
12050 \family typewriter 
12051 ptl_event_kind_t 
12052 \end_inset 
12053 </cell>
12054 <cell alignment="left" valignment="top" usebox="none">
12055 \begin_inset Text
12056
12057 \layout Standard
12058
12059
12060 \begin_inset LatexCommand \ref{sec:ek-type}
12061
12062 \end_inset 
12063
12064
12065 \end_inset 
12066 </cell>
12067 <cell alignment="left" valignment="top" usebox="none">
12068 \begin_inset Text
12069
12070 \layout Standard
12071
12072
12073 \begin_inset LatexCommand \ref{sec:put}
12074
12075 \end_inset 
12076
12077
12078 \end_inset 
12079 </cell>
12080 </row>
12081 <row>
12082 <cell alignment="right" valignment="top" usebox="none">
12083 \begin_inset Text
12084
12085 \layout Standard
12086
12087
12088 \family typewriter 
12089 PTL_EVENT_UNLINK
12090 \end_inset 
12091 </cell>
12092 <cell alignment="left" valignment="top" usebox="none">
12093 \begin_inset Text
12094
12095 \layout Standard
12096
12097 unlink event
12098 \end_inset 
12099 </cell>
12100 <cell alignment="right" valignment="top" usebox="none">
12101 \begin_inset Text
12102
12103 \layout Standard
12104
12105
12106 \family typewriter 
12107 ptl_event_kind_t 
12108 \end_inset 
12109 </cell>
12110 <cell alignment="left" valignment="top" usebox="none">
12111 \begin_inset Text
12112
12113 \layout Standard
12114
12115
12116 \begin_inset LatexCommand \ref{sec:ek-type}
12117
12118 \end_inset 
12119
12120
12121 \end_inset 
12122 </cell>
12123 <cell alignment="left" valignment="top" usebox="none">
12124 \begin_inset Text
12125
12126 \layout Standard
12127
12128
12129 \begin_inset LatexCommand \ref{sec:md-type}
12130
12131 \end_inset 
12132
12133
12134 \end_inset 
12135 </cell>
12136 </row>
12137 <row>
12138 <cell alignment="right" valignment="top" usebox="none">
12139 \begin_inset Text
12140
12141 \layout Standard
12142
12143
12144 \family typewriter 
12145 PTL_PID_ANY 
12146 \end_inset 
12147 </cell>
12148 <cell alignment="left" valignment="top" usebox="none">
12149 \begin_inset Text
12150
12151 \layout Standard
12152
12153 wildcard for process id fields 
12154 \end_inset 
12155 </cell>
12156 <cell alignment="right" valignment="top" usebox="none">
12157 \begin_inset Text
12158
12159 \layout Standard
12160
12161
12162 \family typewriter 
12163 ptl_pid_t 
12164 \end_inset 
12165 </cell>
12166 <cell alignment="left" valignment="top" usebox="none">
12167 \begin_inset Text
12168
12169 \layout Standard
12170
12171  
12172 \begin_inset LatexCommand \ref{sec:id-type}
12173
12174 \end_inset 
12175
12176
12177 \end_inset 
12178 </cell>
12179 <cell alignment="left" valignment="top" usebox="none">
12180 \begin_inset Text
12181
12182 \layout Standard
12183
12184  
12185 \begin_inset LatexCommand \ref{sec:meattach}
12186
12187 \end_inset 
12188
12189
12190 \begin_inset LatexCommand \ref{sec:acentry}
12191
12192 \end_inset 
12193
12194
12195 \end_inset 
12196 </cell>
12197 </row>
12198 <row>
12199 <cell alignment="right" valignment="top" usebox="none">
12200 \begin_inset Text
12201
12202 \layout Standard
12203
12204
12205 \family typewriter 
12206 PTL_NID_ANY
12207 \end_inset 
12208 </cell>
12209 <cell alignment="left" valignment="top" usebox="none">
12210 \begin_inset Text
12211
12212 \layout Standard
12213
12214 wildcard for node id fields
12215 \end_inset 
12216 </cell>
12217 <cell alignment="right" valignment="top" usebox="none">
12218 \begin_inset Text
12219
12220 \layout Standard
12221
12222
12223 \family typewriter 
12224 ptl_nid_t
12225 \end_inset 
12226 </cell>
12227 <cell alignment="left" valignment="top" usebox="none">
12228 \begin_inset Text
12229
12230 \layout Standard
12231
12232
12233 \begin_inset LatexCommand \ref{sec:id-type}
12234
12235 \end_inset 
12236
12237
12238 \end_inset 
12239 </cell>
12240 <cell alignment="left" valignment="top" usebox="none">
12241 \begin_inset Text
12242
12243 \layout Standard
12244
12245
12246 \begin_inset LatexCommand \ref{sec:meattach}
12247
12248 \end_inset 
12249
12250
12251 \begin_inset LatexCommand \ref{sec:acentry}
12252
12253 \end_inset 
12254
12255
12256 \end_inset 
12257 </cell>
12258 </row>
12259 <row>
12260 <cell alignment="right" valignment="top" usebox="none">
12261 \begin_inset Text
12262
12263 \layout Standard
12264
12265
12266 \family typewriter 
12267 PTL_UID_ANY
12268 \end_inset 
12269 </cell>
12270 <cell alignment="left" valignment="top" usebox="none">
12271 \begin_inset Text
12272
12273 \layout Standard
12274
12275 wildcard for user id
12276 \end_inset 
12277 </cell>
12278 <cell alignment="right" valignment="top" usebox="none">
12279 \begin_inset Text
12280
12281 \layout Standard
12282
12283
12284 \family typewriter 
12285 ptl_uid_t
12286 \end_inset 
12287 </cell>
12288 <cell alignment="left" valignment="top" usebox="none">
12289 \begin_inset Text
12290
12291 \layout Standard
12292
12293
12294 \begin_inset LatexCommand \ref{sec:id-type}
12295
12296 \end_inset 
12297
12298
12299 \end_inset 
12300 </cell>
12301 <cell alignment="left" valignment="top" usebox="none">
12302 \begin_inset Text
12303
12304 \layout Standard
12305
12306
12307 \begin_inset LatexCommand \ref{sec:meattach}
12308
12309 \end_inset 
12310
12311
12312 \begin_inset LatexCommand \ref{sec:acentry}
12313
12314 \end_inset 
12315
12316
12317 \end_inset 
12318 </cell>
12319 </row>
12320 <row>
12321 <cell alignment="right" valignment="top" usebox="none">
12322 \begin_inset Text
12323
12324 \layout Standard
12325
12326
12327 \family typewriter 
12328 PTL_IFACE_DEFAULT 
12329 \end_inset 
12330 </cell>
12331 <cell alignment="left" valignment="top" usebox="none">
12332 \begin_inset Text
12333
12334 \layout Standard
12335
12336 default interface 
12337 \end_inset 
12338 </cell>
12339 <cell alignment="right" valignment="top" usebox="none">
12340 \begin_inset Text
12341
12342 \layout Standard
12343
12344
12345 \family typewriter 
12346 ptl_interface_t 
12347 \end_inset 
12348 </cell>
12349 <cell alignment="left" valignment="top" usebox="none">
12350 \begin_inset Text
12351
12352 \layout Standard
12353
12354  
12355 \begin_inset LatexCommand \ref{sec:ni-type}
12356
12357 \end_inset 
12358
12359
12360 \end_inset 
12361 </cell>
12362 <cell alignment="left" valignment="top" usebox="none">
12363 \begin_inset Text
12364
12365 \layout Standard
12366
12367 \end_inset 
12368 </cell>
12369 </row>
12370 <row>
12371 <cell alignment="right" valignment="top" usebox="none">
12372 \begin_inset Text
12373
12374 \layout Standard
12375
12376
12377 \family typewriter 
12378 PTL_INS_AFTER 
12379 \end_inset 
12380 </cell>
12381 <cell alignment="left" valignment="top" usebox="none">
12382 \begin_inset Text
12383
12384 \layout Standard
12385
12386 insert after 
12387 \end_inset 
12388 </cell>
12389 <cell alignment="right" valignment="top" usebox="none">
12390 \begin_inset Text
12391
12392 \layout Standard
12393
12394
12395 \family typewriter 
12396 ptl_ins_pos_t
12397 \family default 
12398  
12399 \end_inset 
12400 </cell>
12401 <cell alignment="left" valignment="top" usebox="none">
12402 \begin_inset Text
12403
12404 \layout Standard
12405
12406  
12407 \begin_inset LatexCommand \ref{sec:meinsert}
12408
12409 \end_inset 
12410
12411
12412 \end_inset 
12413 </cell>
12414 <cell alignment="left" valignment="top" usebox="none">
12415 \begin_inset Text
12416
12417 \layout Standard
12418
12419 \end_inset 
12420 </cell>
12421 </row>
12422 <row>
12423 <cell alignment="right" valignment="top" usebox="none">
12424 \begin_inset Text
12425
12426 \layout Standard
12427
12428
12429 \family typewriter 
12430 PTL_INS_BEFORE 
12431 \end_inset 
12432 </cell>
12433 <cell alignment="left" valignment="top" usebox="none">
12434 \begin_inset Text
12435
12436 \layout Standard
12437
12438 insert before 
12439 \end_inset 
12440 </cell>
12441 <cell alignment="right" valignment="top" usebox="none">
12442 \begin_inset Text
12443
12444 \layout Standard
12445
12446
12447 \family typewriter 
12448 ptl_ins_pos_t
12449 \family default 
12450  
12451 \end_inset 
12452 </cell>
12453 <cell alignment="left" valignment="top" usebox="none">
12454 \begin_inset Text
12455
12456 \layout Standard
12457
12458  
12459 \begin_inset LatexCommand \ref{sec:meinsert}
12460
12461 \end_inset 
12462
12463
12464 \end_inset 
12465 </cell>
12466 <cell alignment="left" valignment="top" usebox="none">
12467 \begin_inset Text
12468
12469 \layout Standard
12470
12471 \end_inset 
12472 </cell>
12473 </row>
12474 <row>
12475 <cell alignment="right" valignment="top" usebox="none">
12476 \begin_inset Text
12477
12478 \layout Standard
12479
12480
12481 \family typewriter 
12482 PTL_MD_ACK_DISABLE 
12483 \end_inset 
12484 </cell>
12485 <cell alignment="left" valignment="top" usebox="none">
12486 \begin_inset Text
12487
12488 \layout Standard
12489
12490 a flag to disable acknowledgements 
12491 \end_inset 
12492 </cell>
12493 <cell alignment="right" valignment="top" usebox="none">
12494 \begin_inset Text
12495
12496 \layout Standard
12497
12498
12499 \family typewriter 
12500 int
12501 \family default 
12502  
12503 \end_inset 
12504 </cell>
12505 <cell alignment="left" valignment="top" usebox="none">
12506 \begin_inset Text
12507
12508 \layout Standard
12509
12510  
12511 \begin_inset LatexCommand \ref{sec:md-type}
12512
12513 \end_inset 
12514
12515
12516 \end_inset 
12517 </cell>
12518 <cell alignment="left" valignment="top" usebox="none">
12519 \begin_inset Text
12520
12521 \layout Standard
12522
12523 \end_inset 
12524 </cell>
12525 </row>
12526 <row>
12527 <cell alignment="right" valignment="top" usebox="none">
12528 \begin_inset Text
12529
12530 \layout Standard
12531
12532
12533 \family typewriter 
12534 PTL_MD_MANAGE_REMOTE 
12535 \end_inset 
12536 </cell>
12537 <cell alignment="left" valignment="top" usebox="none">
12538 \begin_inset Text
12539
12540 \layout Standard
12541
12542 a flag to enable the use of remote offsets 
12543 \end_inset 
12544 </cell>
12545 <cell alignment="right" valignment="top" usebox="none">
12546 \begin_inset Text
12547
12548 \layout Standard
12549
12550
12551 \family typewriter 
12552 int 
12553 \end_inset 
12554 </cell>
12555 <cell alignment="left" valignment="top" usebox="none">
12556 \begin_inset Text
12557
12558 \layout Standard
12559
12560  
12561 \begin_inset LatexCommand \ref{sec:md-type}
12562
12563 \end_inset 
12564
12565
12566 \end_inset 
12567 </cell>
12568 <cell alignment="left" valignment="top" usebox="none">
12569 \begin_inset Text
12570
12571 \layout Standard
12572
12573  
12574 \begin_inset LatexCommand \ref{sec:put}
12575
12576 \end_inset 
12577
12578
12579 \begin_inset LatexCommand \ref{sec:get}
12580
12581 \end_inset 
12582
12583
12584 \end_inset 
12585 </cell>
12586 </row>
12587 <row>
12588 <cell alignment="right" valignment="top" usebox="none">
12589 \begin_inset Text
12590
12591 \layout Standard
12592
12593
12594 \family typewriter 
12595 PTL_MD_OP_GET 
12596 \end_inset 
12597 </cell>
12598 <cell alignment="left" valignment="top" usebox="none">
12599 \begin_inset Text
12600
12601 \layout Standard
12602
12603 a flag to enable get operations 
12604 \end_inset 
12605 </cell>
12606 <cell alignment="right" valignment="top" usebox="none">
12607 \begin_inset Text
12608
12609 \layout Standard
12610
12611
12612 \family typewriter 
12613 int 
12614 \end_inset 
12615 </cell>
12616 <cell alignment="left" valignment="top" usebox="none">
12617 \begin_inset Text
12618
12619 \layout Standard
12620
12621  
12622 \begin_inset LatexCommand \ref{sec:md-type}
12623
12624 \end_inset 
12625
12626
12627 \end_inset 
12628 </cell>
12629 <cell alignment="left" valignment="top" usebox="none">
12630 \begin_inset Text
12631
12632 \layout Standard
12633
12634 \end_inset 
12635 </cell>
12636 </row>
12637 <row>
12638 <cell alignment="right" valignment="top" usebox="none">
12639 \begin_inset Text
12640
12641 \layout Standard
12642
12643
12644 \family typewriter 
12645 PTL_MD_OP_PUT 
12646 \end_inset 
12647 </cell>
12648 <cell alignment="left" valignment="top" usebox="none">
12649 \begin_inset Text
12650
12651 \layout Standard
12652
12653 a flag to enable put operations 
12654 \end_inset 
12655 </cell>
12656 <cell alignment="right" valignment="top" usebox="none">
12657 \begin_inset Text
12658
12659 \layout Standard
12660
12661
12662 \family typewriter 
12663 int
12664 \family default 
12665  
12666 \end_inset 
12667 </cell>
12668 <cell alignment="left" valignment="top" usebox="none">
12669 \begin_inset Text
12670
12671 \layout Standard
12672
12673  
12674 \begin_inset LatexCommand \ref{sec:md-type}
12675
12676 \end_inset 
12677
12678
12679 \end_inset 
12680 </cell>
12681 <cell alignment="left" valignment="top" usebox="none">
12682 \begin_inset Text
12683
12684 \layout Standard
12685
12686 \end_inset 
12687 </cell>
12688 </row>
12689 <row>
12690 <cell alignment="right" valignment="top" usebox="none">
12691 \begin_inset Text
12692
12693 \layout Standard
12694
12695
12696 \family typewriter 
12697 PTL_MD_THRESH_INF 
12698 \end_inset 
12699 </cell>
12700 <cell alignment="left" valignment="top" usebox="none">
12701 \begin_inset Text
12702
12703 \layout Standard
12704
12705 infinite threshold for a memory descriptor 
12706 \end_inset 
12707 </cell>
12708 <cell alignment="right" valignment="top" usebox="none">
12709 \begin_inset Text
12710
12711 \layout Standard
12712
12713
12714 \family typewriter 
12715 int 
12716 \end_inset 
12717 </cell>
12718 <cell alignment="left" valignment="top" usebox="none">
12719 \begin_inset Text
12720
12721 \layout Standard
12722
12723  
12724 \begin_inset LatexCommand \ref{sec:md-type}
12725
12726 \end_inset 
12727
12728
12729 \end_inset 
12730 </cell>
12731 <cell alignment="left" valignment="top" usebox="none">
12732 \begin_inset Text
12733
12734 \layout Standard
12735
12736 \end_inset 
12737 </cell>
12738 </row>
12739 <row>
12740 <cell alignment="right" valignment="top" usebox="none">
12741 \begin_inset Text
12742
12743 \layout Standard
12744
12745
12746 \family typewriter 
12747 PTL_MD_TRUNCATE 
12748 \end_inset 
12749 </cell>
12750 <cell alignment="left" valignment="top" usebox="none">
12751 \begin_inset Text
12752
12753 \layout Standard
12754
12755 a flag to enable truncation of a request 
12756 \end_inset 
12757 </cell>
12758 <cell alignment="right" valignment="top" usebox="none">
12759 \begin_inset Text
12760
12761 \layout Standard
12762
12763
12764 \family typewriter 
12765 int 
12766 \end_inset 
12767 </cell>
12768 <cell alignment="left" valignment="top" usebox="none">
12769 \begin_inset Text
12770
12771 \layout Standard
12772
12773  
12774 \begin_inset LatexCommand \ref{sec:md-type}
12775
12776 \end_inset 
12777
12778
12779 \end_inset 
12780 </cell>
12781 <cell alignment="left" valignment="top" usebox="none">
12782 \begin_inset Text
12783
12784 \layout Standard
12785
12786 \end_inset 
12787 </cell>
12788 </row>
12789 <row>
12790 <cell alignment="right" valignment="top" usebox="none">
12791 \begin_inset Text
12792
12793 \layout Standard
12794
12795
12796 \family typewriter 
12797 PTL_NOACK_REQ 
12798 \end_inset 
12799 </cell>
12800 <cell alignment="left" valignment="top" usebox="none">
12801 \begin_inset Text
12802
12803 \layout Standard
12804
12805 request no acknowledgement 
12806 \end_inset 
12807 </cell>
12808 <cell alignment="right" valignment="top" usebox="none">
12809 \begin_inset Text
12810
12811 \layout Standard
12812
12813
12814 \family typewriter 
12815 ptl_ack_req_t 
12816 \end_inset 
12817 </cell>
12818 <cell alignment="left" valignment="top" usebox="none">
12819 \begin_inset Text
12820
12821 \layout Standard
12822
12823  
12824 \begin_inset LatexCommand \ref{sec:put}
12825
12826 \end_inset 
12827
12828
12829 \end_inset 
12830 </cell>
12831 <cell alignment="left" valignment="top" usebox="none">
12832 \begin_inset Text
12833
12834 \layout Standard
12835
12836 \end_inset 
12837 </cell>
12838 </row>
12839 <row>
12840 <cell alignment="right" valignment="top" usebox="none">
12841 \begin_inset Text
12842
12843 \layout Standard
12844
12845
12846 \family typewriter 
12847 PTL_PT_INDEX_ANY 
12848 \end_inset 
12849 </cell>
12850 <cell alignment="left" valignment="top" usebox="none">
12851 \begin_inset Text
12852
12853 \layout Standard
12854
12855 wildcard for Portal indexes 
12856 \end_inset 
12857 </cell>
12858 <cell alignment="right" valignment="top" usebox="none">
12859 \begin_inset Text
12860
12861 \layout Standard
12862
12863
12864 \family typewriter 
12865 ptl_pt_index_t
12866 \family default 
12867  
12868 \end_inset 
12869 </cell>
12870 <cell alignment="left" valignment="top" usebox="none">
12871 \begin_inset Text
12872
12873 \layout Standard
12874
12875  
12876 \begin_inset LatexCommand \ref{sec:acentry}
12877
12878 \end_inset 
12879
12880
12881 \end_inset 
12882 </cell>
12883 <cell alignment="left" valignment="top" usebox="none">
12884 \begin_inset Text
12885
12886 \layout Standard
12887
12888 \end_inset 
12889 </cell>
12890 </row>
12891 <row>
12892 <cell alignment="right" valignment="top" usebox="none">
12893 \begin_inset Text
12894
12895 \layout Standard
12896
12897
12898 \family typewriter 
12899 PTL_RETAIN 
12900 \end_inset 
12901 </cell>
12902 <cell alignment="left" valignment="top" usebox="none">
12903 \begin_inset Text
12904
12905 \layout Standard
12906
12907 disable unlinking 
12908 \end_inset 
12909 </cell>
12910 <cell alignment="right" valignment="top" usebox="none">
12911 \begin_inset Text
12912
12913 \layout Standard
12914
12915
12916 \family typewriter 
12917 ptl_unlink_t 
12918 \end_inset 
12919 </cell>
12920 <cell alignment="left" valignment="top" usebox="none">
12921 \begin_inset Text
12922
12923 \layout Standard
12924
12925  
12926 \begin_inset LatexCommand \ref{sec:mdattach}
12927
12928 \end_inset 
12929
12930
12931 \end_inset 
12932 </cell>
12933 <cell alignment="left" valignment="top" usebox="none">
12934 \begin_inset Text
12935
12936 \layout Standard
12937
12938 \end_inset 
12939 </cell>
12940 </row>
12941 <row>
12942 <cell alignment="right" valignment="top" usebox="none">
12943 \begin_inset Text
12944
12945 \layout Standard
12946
12947
12948 \family typewriter 
12949 PTL_SR_DROP_COUNT 
12950 \end_inset 
12951 </cell>
12952 <cell alignment="left" valignment="top" usebox="none">
12953 \begin_inset Text
12954
12955 \layout Standard
12956
12957 index for the dropped count register 
12958 \end_inset 
12959 </cell>
12960 <cell alignment="right" valignment="top" usebox="none">
12961 \begin_inset Text
12962
12963 \layout Standard
12964
12965
12966 \family typewriter 
12967 ptl_sr_index_t 
12968 \end_inset 
12969 </cell>
12970 <cell alignment="left" valignment="top" usebox="none">
12971 \begin_inset Text
12972
12973 \layout Standard
12974
12975  
12976 \begin_inset LatexCommand \ref{sec:stat-type}
12977
12978 \end_inset 
12979
12980
12981 \end_inset 
12982 </cell>
12983 <cell alignment="left" valignment="top" usebox="none">
12984 \begin_inset Text
12985
12986 \layout Standard
12987
12988  
12989 \begin_inset LatexCommand \ref{sec:nistatus}
12990
12991 \end_inset 
12992
12993
12994 \end_inset 
12995 </cell>
12996 </row>
12997 <row>
12998 <cell alignment="right" valignment="top" usebox="none">
12999 \begin_inset Text
13000
13001 \layout Standard
13002
13003
13004 \family typewriter 
13005 PTL_UNLINK 
13006 \end_inset 
13007 </cell>
13008 <cell alignment="left" valignment="top" usebox="none">
13009 \begin_inset Text
13010
13011 \layout Standard
13012
13013 enable unlinking 
13014 \end_inset 
13015 </cell>
13016 <cell alignment="right" valignment="top" usebox="none">
13017 \begin_inset Text
13018
13019 \layout Standard
13020
13021
13022 \family typewriter 
13023 ptl_unlink_t 
13024 \end_inset 
13025 </cell>
13026 <cell alignment="left" valignment="top" usebox="none">
13027 \begin_inset Text
13028
13029 \layout Standard
13030
13031  
13032 \begin_inset LatexCommand \ref{sec:mdattach}
13033
13034 \end_inset 
13035
13036
13037 \end_inset 
13038 </cell>
13039 <cell alignment="left" valignment="top" usebox="none">
13040 \begin_inset Text
13041
13042 \layout Standard
13043
13044 \end_inset 
13045 </cell>
13046 </row>
13047 </lyxtabular>
13048
13049 \end_inset 
13050
13051
13052 \end_inset 
13053
13054
13055 \layout Chapter
13056
13057 The Semantics of Message Transmission
13058 \begin_inset LatexCommand \label{sec:semantics}
13059
13060 \end_inset 
13061
13062
13063 \layout Standard
13064
13065 The portals API uses four types of messages: put requests, acknowledgements,
13066  get requests, and replies.
13067  In this section, we describe the information passed on the wire for each
13068  type of message.
13069  We also describe how this information is used to process incoming messages.
13070 \layout Section
13071
13072 Sending Messages
13073 \layout Standard
13074
13075 Table\SpecialChar ~
13076
13077 \begin_inset LatexCommand \ref{tab:put-wire}
13078
13079 \end_inset 
13080
13081  summarizes the information that is transmitted for a put request.
13082  The first column provides a descriptive name for the information, the second
13083  column provides the type for this information, the third column identifies
13084  the source of the information, and the fourth column provides additional
13085  notes.
13086  Most information that is transmitted is obtained directly from the 
13087 \emph on 
13088 PtlPut
13089 \emph default 
13090  operation.
13091  Notice that the handle for the memory descriptor used in the 
13092 \emph on 
13093 PtlPut
13094 \emph default 
13095  operation is transmitted even though this value cannot be interpreted by
13096  the target.
13097  A value of anything other than 
13098 \family typewriter 
13099 PTL_MD_NONE
13100 \family default 
13101 , is interpreted as a request for an acknowledgement.
13102 \layout Standard
13103
13104
13105 \begin_inset Float table
13106 placement htbp
13107 wide false
13108 collapsed false
13109
13110 \layout Caption
13111
13112 Information Passed in a Put Request
13113 \begin_inset LatexCommand \label{tab:put-wire}
13114
13115 \end_inset 
13116
13117
13118 \layout Standard
13119
13120
13121 \begin_inset ERT
13122 status Collapsed
13123
13124 \layout Standard
13125
13126 \backslash 
13127 medskip
13128 \end_inset 
13129
13130
13131 \layout Standard
13132 \align center 
13133
13134 \size small 
13135
13136 \begin_inset  Tabular
13137 <lyxtabular version="3" rows="12" columns="4">
13138 <features firstHeadEmpty="true">
13139 <column alignment="left" valignment="top" width="0pt">
13140 <column alignment="left" valignment="top" width="0pt">
13141 <column alignment="left" valignment="top" width="0pt">
13142 <column alignment="left" valignment="top" width="0pt">
13143 <row bottomline="true">
13144 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13145 \begin_inset Text
13146
13147 \layout Standard
13148
13149
13150 \series bold 
13151 Information 
13152 \end_inset 
13153 </cell>
13154 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13155 \begin_inset Text
13156
13157 \layout Standard
13158
13159
13160 \series bold 
13161 Type
13162 \end_inset 
13163 </cell>
13164 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13165 \begin_inset Text
13166
13167 \layout Standard
13168
13169
13170 \series bold 
13171 \emph on 
13172 PtlPut
13173 \emph default 
13174  arg
13175 \end_inset 
13176 </cell>
13177 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13178 \begin_inset Text
13179
13180 \layout Standard
13181
13182
13183 \series bold 
13184 Notes 
13185 \end_inset 
13186 </cell>
13187 </row>
13188 <row>
13189 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13190 \begin_inset Text
13191
13192 \layout Standard
13193
13194 operation 
13195 \end_inset 
13196 </cell>
13197 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13198 \begin_inset Text
13199
13200 \layout Standard
13201
13202
13203 \family typewriter 
13204 int 
13205 \end_inset 
13206 </cell>
13207 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13208 \begin_inset Text
13209
13210 \layout Standard
13211
13212 \end_inset 
13213 </cell>
13214 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13215 \begin_inset Text
13216
13217 \layout Standard
13218
13219 indicates a put request 
13220 \end_inset 
13221 </cell>
13222 </row>
13223 <row>
13224 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13225 \begin_inset Text
13226
13227 \layout Standard
13228
13229 initiator 
13230 \end_inset 
13231 </cell>
13232 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13233 \begin_inset Text
13234
13235 \layout Standard
13236
13237
13238 \family typewriter 
13239 ptl_process_id_t 
13240 \end_inset 
13241 </cell>
13242 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13243 \begin_inset Text
13244
13245 \layout Standard
13246
13247 \end_inset 
13248 </cell>
13249 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13250 \begin_inset Text
13251
13252 \layout Standard
13253
13254 local information 
13255 \end_inset 
13256 </cell>
13257 </row>
13258 <row>
13259 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13260 \begin_inset Text
13261
13262 \layout Standard
13263
13264 user
13265 \end_inset 
13266 </cell>
13267 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13268 \begin_inset Text
13269
13270 \layout Standard
13271
13272
13273 \family typewriter 
13274 ptl_uid_t
13275 \end_inset 
13276 </cell>
13277 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13278 \begin_inset Text
13279
13280 \layout Standard
13281
13282 \end_inset 
13283 </cell>
13284 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13285 \begin_inset Text
13286
13287 \layout Standard
13288
13289 local information
13290 \end_inset 
13291 </cell>
13292 </row>
13293 <row>
13294 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13295 \begin_inset Text
13296
13297 \layout Standard
13298
13299 target 
13300 \end_inset 
13301 </cell>
13302 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13303 \begin_inset Text
13304
13305 \layout Standard
13306
13307
13308 \family typewriter 
13309 ptl_process_id_t 
13310 \end_inset 
13311 </cell>
13312 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13313 \begin_inset Text
13314
13315 \layout Standard
13316
13317
13318 \family typewriter 
13319 target
13320 \family default 
13321  
13322 \end_inset 
13323 </cell>
13324 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13325 \begin_inset Text
13326
13327 \layout Standard
13328
13329 \end_inset 
13330 </cell>
13331 </row>
13332 <row>
13333 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13334 \begin_inset Text
13335
13336 \layout Standard
13337
13338 portal index 
13339 \end_inset 
13340 </cell>
13341 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13342 \begin_inset Text
13343
13344 \layout Standard
13345
13346
13347 \family typewriter 
13348 ptl_pt_index_t
13349 \family default 
13350  
13351 \end_inset 
13352 </cell>
13353 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13354 \begin_inset Text
13355
13356 \layout Standard
13357
13358
13359 \family typewriter 
13360 portal 
13361 \end_inset 
13362 </cell>
13363 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13364 \begin_inset Text
13365
13366 \layout Standard
13367
13368 \end_inset 
13369 </cell>
13370 </row>
13371 <row>
13372 <cell alignment="left" valignment="top" usebox="none">
13373 \begin_inset Text
13374
13375 \layout Standard
13376
13377 cookie 
13378 \end_inset 
13379 </cell>
13380 <cell alignment="right" valignment="top" usebox="none">
13381 \begin_inset Text
13382
13383 \layout Standard
13384
13385
13386 \family typewriter 
13387 ptl_ac_index_t 
13388 \end_inset 
13389 </cell>
13390 <cell alignment="left" valignment="top" usebox="none">
13391 \begin_inset Text
13392
13393 \layout Standard
13394
13395
13396 \family typewriter 
13397 cookie
13398 \family default 
13399  
13400 \end_inset 
13401 </cell>
13402 <cell alignment="right" valignment="top" usebox="none">
13403 \begin_inset Text
13404
13405 \layout Standard
13406
13407 \end_inset 
13408 </cell>
13409 </row>
13410 <row>
13411 <cell alignment="left" valignment="top" usebox="none">
13412 \begin_inset Text
13413
13414 \layout Standard
13415
13416 match bits 
13417 \end_inset 
13418 </cell>
13419 <cell alignment="right" valignment="top" usebox="none">
13420 \begin_inset Text
13421
13422 \layout Standard
13423
13424
13425 \family typewriter 
13426 ptl_match_bits_t 
13427 \end_inset 
13428 </cell>
13429 <cell alignment="left" valignment="top" usebox="none">
13430 \begin_inset Text
13431
13432 \layout Standard
13433
13434
13435 \family typewriter 
13436 match_bits 
13437 \end_inset 
13438 </cell>
13439 <cell alignment="right" valignment="top" usebox="none">
13440 \begin_inset Text
13441
13442 \layout Standard
13443
13444 \end_inset 
13445 </cell>
13446 </row>
13447 <row>
13448 <cell alignment="left" valignment="top" usebox="none">
13449 \begin_inset Text
13450
13451 \layout Standard
13452
13453 offset 
13454 \end_inset 
13455 </cell>
13456 <cell alignment="right" valignment="top" usebox="none">
13457 \begin_inset Text
13458
13459 \layout Standard
13460
13461
13462 \family typewriter 
13463 ptl_size_t 
13464 \end_inset 
13465 </cell>
13466 <cell alignment="left" valignment="top" usebox="none">
13467 \begin_inset Text
13468
13469 \layout Standard
13470
13471
13472 \family typewriter 
13473 offset
13474 \family default 
13475  
13476 \end_inset 
13477 </cell>
13478 <cell alignment="right" valignment="top" usebox="none">
13479 \begin_inset Text
13480
13481 \layout Standard
13482
13483 \end_inset 
13484 </cell>
13485 </row>
13486 <row>
13487 <cell alignment="left" valignment="top" usebox="none">
13488 \begin_inset Text
13489
13490 \layout Standard
13491
13492 memory desc 
13493 \end_inset 
13494 </cell>
13495 <cell alignment="right" valignment="top" usebox="none">
13496 \begin_inset Text
13497
13498 \layout Standard
13499
13500
13501 \family typewriter 
13502 ptl_handle_md_t 
13503 \end_inset 
13504 </cell>
13505 <cell alignment="left" valignment="top" usebox="none">
13506 \begin_inset Text
13507
13508 \layout Standard
13509
13510
13511 \family typewriter 
13512 mem_desc
13513 \family default 
13514  
13515 \end_inset 
13516 </cell>
13517 <cell alignment="right" valignment="top" usebox="none">
13518 \begin_inset Text
13519
13520 \layout Standard
13521
13522 no ack if 
13523 \family typewriter 
13524 PTL_MD_NONE
13525 \end_inset 
13526 </cell>
13527 </row>
13528 <row>
13529 <cell alignment="left" valignment="top" usebox="none">
13530 \begin_inset Text
13531
13532 \layout Standard
13533
13534 length 
13535 \end_inset 
13536 </cell>
13537 <cell alignment="right" valignment="top" usebox="none">
13538 \begin_inset Text
13539
13540 \layout Standard
13541
13542
13543 \family typewriter 
13544 ptl_size_t 
13545 \end_inset 
13546 </cell>
13547 <cell alignment="left" valignment="top" usebox="none">
13548 \begin_inset Text
13549
13550 \layout Standard
13551
13552
13553 \family typewriter 
13554 mem_desc 
13555 \end_inset 
13556 </cell>
13557 <cell alignment="right" valignment="top" usebox="none">
13558 \begin_inset Text
13559
13560 \layout Standard
13561
13562
13563 \family typewriter 
13564 length
13565 \family default 
13566  member 
13567 \end_inset 
13568 </cell>
13569 </row>
13570 <row>
13571 <cell alignment="left" valignment="top" usebox="none">
13572 \begin_inset Text
13573
13574 \layout Standard
13575
13576 data 
13577 \end_inset 
13578 </cell>
13579 <cell alignment="right" valignment="top" usebox="none">
13580 \begin_inset Text
13581
13582 \layout Standard
13583
13584
13585 \family roman 
13586 \emph on 
13587 bytes
13588 \end_inset 
13589 </cell>
13590 <cell alignment="left" valignment="top" usebox="none">
13591 \begin_inset Text
13592
13593 \layout Standard
13594
13595
13596 \family typewriter 
13597 mem_desc 
13598 \end_inset 
13599 </cell>
13600 <cell alignment="right" valignment="top" usebox="none">
13601 \begin_inset Text
13602
13603 \layout Standard
13604
13605
13606 \family typewriter 
13607 start
13608 \family default 
13609  and 
13610 \family typewriter 
13611 length
13612 \family default 
13613  members 
13614 \end_inset 
13615 </cell>
13616 </row>
13617 </lyxtabular>
13618
13619 \end_inset 
13620
13621
13622 \end_inset 
13623
13624
13625 \layout Standard
13626
13627 Table\SpecialChar ~
13628
13629 \begin_inset LatexCommand \ref{tab:ack-wire}
13630
13631 \end_inset 
13632
13633  summarizes the information transmitted in an acknowledgement.
13634  Most of the information is simply echoed from the put request.
13635  Notice that the initiator and target are obtained directly from the put
13636  request, but are swapped in generating the acknowledgement.
13637  The only new piece of information in the acknowledgement is the manipulated
13638  length which is determined as the put request is satisfied.
13639 \layout Standard
13640
13641
13642 \begin_inset Float table
13643 placement htbp
13644 wide false
13645 collapsed false
13646
13647 \layout Caption
13648
13649 Information Passed in an Acknowledgement
13650 \begin_inset LatexCommand \label{tab:ack-wire}
13651
13652 \end_inset 
13653
13654
13655 \layout Standard
13656
13657
13658 \begin_inset ERT
13659 status Collapsed
13660
13661 \layout Standard
13662
13663 \backslash 
13664 medskip  
13665 \end_inset 
13666
13667
13668 \layout Standard
13669 \align center 
13670
13671 \size small 
13672
13673 \begin_inset  Tabular
13674 <lyxtabular version="3" rows="10" columns="4">
13675 <features firstHeadEmpty="true">
13676 <column alignment="left" valignment="top" width="0pt">
13677 <column alignment="left" valignment="top" width="0pt">
13678 <column alignment="left" valignment="top" width="0pt">
13679 <column alignment="left" valignment="top" width="0pt">
13680 <row bottomline="true">
13681 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13682 \begin_inset Text
13683
13684 \layout Standard
13685
13686  
13687 \series bold 
13688 Information
13689 \series default 
13690  
13691 \end_inset 
13692 </cell>
13693 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13694 \begin_inset Text
13695
13696 \layout Standard
13697
13698  
13699 \series bold 
13700 Type
13701 \end_inset 
13702 </cell>
13703 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13704 \begin_inset Text
13705
13706 \layout Standard
13707
13708  
13709 \series bold 
13710 Put Information 
13711 \end_inset 
13712 </cell>
13713 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13714 \begin_inset Text
13715
13716 \layout Standard
13717
13718  
13719 \series bold 
13720 Notes 
13721 \end_inset 
13722 </cell>
13723 </row>
13724 <row>
13725 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13726 \begin_inset Text
13727
13728 \layout Standard
13729
13730 operation 
13731 \end_inset 
13732 </cell>
13733 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13734 \begin_inset Text
13735
13736 \layout Standard
13737
13738  
13739 \family typewriter 
13740 int 
13741 \end_inset 
13742 </cell>
13743 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13744 \begin_inset Text
13745
13746 \layout Standard
13747
13748 \end_inset 
13749 </cell>
13750 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13751 \begin_inset Text
13752
13753 \layout Standard
13754
13755  indicates an acknowledgement 
13756 \end_inset 
13757 </cell>
13758 </row>
13759 <row>
13760 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13761 \begin_inset Text
13762
13763 \layout Standard
13764
13765  initiator 
13766 \end_inset 
13767 </cell>
13768 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13769 \begin_inset Text
13770
13771 \layout Standard
13772
13773  
13774 \family typewriter 
13775 ptl_process_id_t 
13776 \end_inset 
13777 </cell>
13778 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13779 \begin_inset Text
13780
13781 \layout Standard
13782
13783  target 
13784 \end_inset 
13785 </cell>
13786 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13787 \begin_inset Text
13788
13789 \layout Standard
13790
13791 \end_inset 
13792 </cell>
13793 </row>
13794 <row>
13795 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13796 \begin_inset Text
13797
13798 \layout Standard
13799
13800  target 
13801 \end_inset 
13802 </cell>
13803 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13804 \begin_inset Text
13805
13806 \layout Standard
13807
13808  
13809 \family typewriter 
13810 ptl_process_id_t 
13811 \end_inset 
13812 </cell>
13813 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
13814 \begin_inset Text
13815
13816 \layout Standard
13817
13818  initiator 
13819 \end_inset 
13820 </cell>
13821 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
13822 \begin_inset Text
13823
13824 \layout Standard
13825
13826 \end_inset 
13827 </cell>
13828 </row>
13829 <row>
13830 <cell alignment="left" valignment="top" usebox="none">
13831 \begin_inset Text
13832
13833 \layout Standard
13834
13835  portal index 
13836 \end_inset 
13837 </cell>
13838 <cell alignment="right" valignment="top" usebox="none">
13839 \begin_inset Text
13840
13841 \layout Standard
13842
13843  
13844 \family typewriter 
13845 ptl_pt_index_t 
13846 \end_inset 
13847 </cell>
13848 <cell alignment="left" valignment="top" usebox="none">
13849 \begin_inset Text
13850
13851 \layout Standard
13852
13853  portal index 
13854 \end_inset 
13855 </cell>
13856 <cell alignment="right" valignment="top" usebox="none">
13857 \begin_inset Text
13858
13859 \layout Standard
13860
13861  echo 
13862 \end_inset 
13863 </cell>
13864 </row>
13865 <row>
13866 <cell alignment="left" valignment="top" usebox="none">
13867 \begin_inset Text
13868
13869 \layout Standard
13870
13871  match bits 
13872 \end_inset 
13873 </cell>
13874 <cell alignment="right" valignment="top" usebox="none">
13875 \begin_inset Text
13876
13877 \layout Standard
13878
13879  
13880 \family typewriter 
13881 ptl_match_bits_t 
13882 \end_inset 
13883 </cell>
13884 <cell alignment="left" valignment="top" usebox="none">
13885 \begin_inset Text
13886
13887 \layout Standard
13888
13889  match bits 
13890 \end_inset 
13891 </cell>
13892 <cell alignment="right" valignment="top" usebox="none">
13893 \begin_inset Text
13894
13895 \layout Standard
13896
13897  echo 
13898 \end_inset 
13899 </cell>
13900 </row>
13901 <row>
13902 <cell alignment="left" valignment="top" usebox="none">
13903 \begin_inset Text
13904
13905 \layout Standard
13906
13907  offset 
13908 \end_inset 
13909 </cell>
13910 <cell alignment="right" valignment="top" usebox="none">
13911 \begin_inset Text
13912
13913 \layout Standard
13914
13915  
13916 \family typewriter 
13917 ptl_size_t 
13918 \end_inset 
13919 </cell>
13920 <cell alignment="left" valignment="top" usebox="none">
13921 \begin_inset Text
13922
13923 \layout Standard
13924
13925  offset 
13926 \end_inset 
13927 </cell>
13928 <cell alignment="right" valignment="top" usebox="none">
13929 \begin_inset Text
13930
13931 \layout Standard
13932
13933  echo 
13934 \end_inset 
13935 </cell>
13936 </row>
13937 <row>
13938 <cell alignment="left" valignment="top" usebox="none">
13939 \begin_inset Text
13940
13941 \layout Standard
13942
13943  memory desc 
13944 \end_inset 
13945 </cell>
13946 <cell alignment="right" valignment="top" usebox="none">
13947 \begin_inset Text
13948
13949 \layout Standard
13950
13951
13952 \family typewriter 
13953  ptl_handle_md_t 
13954 \end_inset 
13955 </cell>
13956 <cell alignment="left" valignment="top" usebox="none">
13957 \begin_inset Text
13958
13959 \layout Standard
13960
13961  memory desc 
13962 \end_inset 
13963 </cell>
13964 <cell alignment="right" valignment="top" usebox="none">
13965 \begin_inset Text
13966
13967 \layout Standard
13968
13969  echo 
13970 \end_inset 
13971 </cell>
13972 </row>
13973 <row>
13974 <cell alignment="left" valignment="top" usebox="none">
13975 \begin_inset Text
13976
13977 \layout Standard
13978
13979  requested length 
13980 \end_inset 
13981 </cell>
13982 <cell alignment="right" valignment="top" usebox="none">
13983 \begin_inset Text
13984
13985 \layout Standard
13986
13987
13988 \family typewriter 
13989  ptl_size_t
13990 \family default 
13991  
13992 \end_inset 
13993 </cell>
13994 <cell alignment="left" valignment="top" usebox="none">
13995 \begin_inset Text
13996
13997 \layout Standard
13998
13999  length 
14000 \end_inset 
14001 </cell>
14002 <cell alignment="right" valignment="top" usebox="none">
14003 \begin_inset Text
14004
14005 \layout Standard
14006
14007  echo 
14008 \end_inset 
14009 </cell>
14010 </row>
14011 <row>
14012 <cell alignment="left" valignment="top" usebox="none">
14013 \begin_inset Text
14014
14015 \layout Standard
14016
14017  manipulated length 
14018 \end_inset 
14019 </cell>
14020 <cell alignment="right" valignment="top" usebox="none">
14021 \begin_inset Text
14022
14023 \layout Standard
14024
14025
14026 \family typewriter 
14027  ptl_size_t
14028 \family default 
14029  
14030 \end_inset 
14031 </cell>
14032 <cell alignment="left" valignment="top" usebox="none">
14033 \begin_inset Text
14034
14035 \layout Standard
14036
14037 \end_inset 
14038 </cell>
14039 <cell alignment="right" valignment="top" usebox="none">
14040 \begin_inset Text
14041
14042 \layout Standard
14043
14044  obtained from the operation 
14045 \end_inset 
14046 </cell>
14047 </row>
14048 </lyxtabular>
14049
14050 \end_inset 
14051
14052
14053 \end_inset 
14054
14055
14056 \layout Standard
14057
14058 Table\SpecialChar ~
14059
14060 \begin_inset LatexCommand \ref{tab:get-wire}
14061
14062 \end_inset 
14063
14064  summarizes the information that is transmitted for a get request.
14065  Like the information transmitted in a put request, most of the information
14066  transmitted in a get request is obtained directly from the 
14067 \emph on 
14068 PtlGet
14069 \emph default 
14070  operation.
14071  Unlike put requests, get requests do not include the event queue handle.
14072  In this case, the reply is generated whenever the operation succeeds and
14073  the memory descriptor must not be unlinked until the reply is received.
14074  As such, there is no advantage to explicitly sending the event queue handle.
14075 \layout Standard
14076
14077
14078 \begin_inset Float table
14079 placement htbp
14080 wide false
14081 collapsed false
14082
14083 \layout Caption
14084
14085 Information Passed in a Get Request
14086 \begin_inset LatexCommand \label{tab:get-wire}
14087
14088 \end_inset 
14089
14090
14091 \layout Standard
14092
14093
14094 \begin_inset ERT
14095 status Collapsed
14096
14097 \layout Standard
14098
14099 \backslash 
14100 medskip  
14101 \end_inset 
14102
14103
14104 \layout Standard
14105 \align center 
14106
14107 \size small 
14108
14109 \begin_inset  Tabular
14110 <lyxtabular version="3" rows="11" columns="4">
14111 <features firstHeadEmpty="true">
14112 <column alignment="left" valignment="top" width="0pt">
14113 <column alignment="left" valignment="top" width="0pt">
14114 <column alignment="left" valignment="top" width="0pt">
14115 <column alignment="left" valignment="top" width="0pt">
14116 <row bottomline="true">
14117 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14118 \begin_inset Text
14119
14120 \layout Standard
14121
14122
14123 \series bold 
14124 Information
14125 \series default 
14126  
14127 \end_inset 
14128 </cell>
14129 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14130 \begin_inset Text
14131
14132 \layout Standard
14133
14134
14135 \series bold 
14136 Type
14137 \end_inset 
14138 </cell>
14139 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14140 \begin_inset Text
14141
14142 \layout Standard
14143
14144
14145 \series bold 
14146 \emph on 
14147 PtlGet
14148 \emph default 
14149  argument
14150 \end_inset 
14151 </cell>
14152 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14153 \begin_inset Text
14154
14155 \layout Standard
14156
14157
14158 \series bold 
14159 Notes 
14160 \end_inset 
14161 </cell>
14162 </row>
14163 <row>
14164 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14165 \begin_inset Text
14166
14167 \layout Standard
14168
14169 operation 
14170 \end_inset 
14171 </cell>
14172 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14173 \begin_inset Text
14174
14175 \layout Standard
14176
14177
14178 \family typewriter 
14179 int 
14180 \end_inset 
14181 </cell>
14182 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14183 \begin_inset Text
14184
14185 \layout Standard
14186
14187 \end_inset 
14188 </cell>
14189 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14190 \begin_inset Text
14191
14192 \layout Standard
14193
14194 indicates a get operation 
14195 \end_inset 
14196 </cell>
14197 </row>
14198 <row>
14199 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14200 \begin_inset Text
14201
14202 \layout Standard
14203
14204 initiator 
14205 \end_inset 
14206 </cell>
14207 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14208 \begin_inset Text
14209
14210 \layout Standard
14211
14212
14213 \family typewriter 
14214 ptl_process_id_t 
14215 \end_inset 
14216 </cell>
14217 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14218 \begin_inset Text
14219
14220 \layout Standard
14221
14222 \end_inset 
14223 </cell>
14224 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14225 \begin_inset Text
14226
14227 \layout Standard
14228
14229 local information 
14230 \end_inset 
14231 </cell>
14232 </row>
14233 <row>
14234 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14235 \begin_inset Text
14236
14237 \layout Standard
14238
14239 user
14240 \end_inset 
14241 </cell>
14242 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14243 \begin_inset Text
14244
14245 \layout Standard
14246
14247
14248 \family typewriter 
14249 ptl_uid_t
14250 \end_inset 
14251 </cell>
14252 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14253 \begin_inset Text
14254
14255 \layout Standard
14256
14257 \end_inset 
14258 </cell>
14259 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14260 \begin_inset Text
14261
14262 \layout Standard
14263
14264 local information
14265 \end_inset 
14266 </cell>
14267 </row>
14268 <row>
14269 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14270 \begin_inset Text
14271
14272 \layout Standard
14273
14274 target 
14275 \end_inset 
14276 </cell>
14277 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14278 \begin_inset Text
14279
14280 \layout Standard
14281
14282
14283 \family typewriter 
14284 ptl_process_id_t 
14285 \end_inset 
14286 </cell>
14287 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14288 \begin_inset Text
14289
14290 \layout Standard
14291
14292
14293 \family typewriter 
14294 target 
14295 \end_inset 
14296 </cell>
14297 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14298 \begin_inset Text
14299
14300 \layout Standard
14301
14302 \end_inset 
14303 </cell>
14304 </row>
14305 <row>
14306 <cell alignment="left" valignment="top" usebox="none">
14307 \begin_inset Text
14308
14309 \layout Standard
14310
14311 portal index 
14312 \end_inset 
14313 </cell>
14314 <cell alignment="right" valignment="top" usebox="none">
14315 \begin_inset Text
14316
14317 \layout Standard
14318
14319
14320 \family typewriter 
14321 ptl_pt_index_t 
14322 \end_inset 
14323 </cell>
14324 <cell alignment="left" valignment="top" usebox="none">
14325 \begin_inset Text
14326
14327 \layout Standard
14328
14329
14330 \family typewriter 
14331 portal
14332 \family default 
14333  
14334 \end_inset 
14335 </cell>
14336 <cell alignment="right" valignment="top" usebox="none">
14337 \begin_inset Text
14338
14339 \layout Standard
14340
14341 \end_inset 
14342 </cell>
14343 </row>
14344 <row>
14345 <cell alignment="left" valignment="top" usebox="none">
14346 \begin_inset Text
14347
14348 \layout Standard
14349
14350 cookie 
14351 \end_inset 
14352 </cell>
14353 <cell alignment="right" valignment="top" usebox="none">
14354 \begin_inset Text
14355
14356 \layout Standard
14357
14358
14359 \family typewriter 
14360 ptl_ac_index_t 
14361 \end_inset 
14362 </cell>
14363 <cell alignment="left" valignment="top" usebox="none">
14364 \begin_inset Text
14365
14366 \layout Standard
14367
14368
14369 \family typewriter 
14370 cookie 
14371 \end_inset 
14372 </cell>
14373 <cell alignment="right" valignment="top" usebox="none">
14374 \begin_inset Text
14375
14376 \layout Standard
14377
14378 \end_inset 
14379 </cell>
14380 </row>
14381 <row>
14382 <cell alignment="left" valignment="top" usebox="none">
14383 \begin_inset Text
14384
14385 \layout Standard
14386
14387 match bits 
14388 \end_inset 
14389 </cell>
14390 <cell alignment="right" valignment="top" usebox="none">
14391 \begin_inset Text
14392
14393 \layout Standard
14394
14395
14396 \family typewriter 
14397 ptl_match_bits_t 
14398 \end_inset 
14399 </cell>
14400 <cell alignment="left" valignment="top" usebox="none">
14401 \begin_inset Text
14402
14403 \layout Standard
14404
14405
14406 \family typewriter 
14407 match_bits
14408 \family default 
14409  
14410 \end_inset 
14411 </cell>
14412 <cell alignment="right" valignment="top" usebox="none">
14413 \begin_inset Text
14414
14415 \layout Standard
14416
14417 \end_inset 
14418 </cell>
14419 </row>
14420 <row>
14421 <cell alignment="left" valignment="top" usebox="none">
14422 \begin_inset Text
14423
14424 \layout Standard
14425
14426 offset 
14427 \end_inset 
14428 </cell>
14429 <cell alignment="right" valignment="top" usebox="none">
14430 \begin_inset Text
14431
14432 \layout Standard
14433
14434
14435 \family typewriter 
14436 ptl_size_t 
14437 \end_inset 
14438 </cell>
14439 <cell alignment="left" valignment="top" usebox="none">
14440 \begin_inset Text
14441
14442 \layout Standard
14443
14444
14445 \family typewriter 
14446 offset 
14447 \end_inset 
14448 </cell>
14449 <cell alignment="right" valignment="top" usebox="none">
14450 \begin_inset Text
14451
14452 \layout Standard
14453
14454 \end_inset 
14455 </cell>
14456 </row>
14457 <row>
14458 <cell alignment="left" valignment="top" usebox="none">
14459 \begin_inset Text
14460
14461 \layout Standard
14462
14463 memory desc 
14464 \end_inset 
14465 </cell>
14466 <cell alignment="right" valignment="top" usebox="none">
14467 \begin_inset Text
14468
14469 \layout Standard
14470
14471
14472 \family typewriter 
14473 ptl_handle_md_t 
14474 \end_inset 
14475 </cell>
14476 <cell alignment="left" valignment="top" usebox="none">
14477 \begin_inset Text
14478
14479 \layout Standard
14480
14481
14482 \family typewriter 
14483 mem_desc
14484 \family default 
14485  
14486 \end_inset 
14487 </cell>
14488 <cell alignment="right" valignment="top" usebox="none">
14489 \begin_inset Text
14490
14491 \layout Standard
14492
14493 \end_inset 
14494 </cell>
14495 </row>
14496 <row>
14497 <cell alignment="left" valignment="top" usebox="none">
14498 \begin_inset Text
14499
14500 \layout Standard
14501
14502 length 
14503 \end_inset 
14504 </cell>
14505 <cell alignment="right" valignment="top" usebox="none">
14506 \begin_inset Text
14507
14508 \layout Standard
14509
14510
14511 \family typewriter 
14512 ptl_size_t 
14513 \end_inset 
14514 </cell>
14515 <cell alignment="left" valignment="top" usebox="none">
14516 \begin_inset Text
14517
14518 \layout Standard
14519
14520
14521 \family typewriter 
14522 mem_desc 
14523 \end_inset 
14524 </cell>
14525 <cell alignment="right" valignment="top" usebox="none">
14526 \begin_inset Text
14527
14528 \layout Standard
14529
14530
14531 \family typewriter 
14532 length
14533 \family default 
14534  member 
14535 \end_inset 
14536 </cell>
14537 </row>
14538 </lyxtabular>
14539
14540 \end_inset 
14541
14542
14543 \end_inset 
14544
14545
14546 \layout Standard
14547
14548 Table\SpecialChar ~
14549
14550 \begin_inset LatexCommand \ref{tab:reply-wire}
14551
14552 \end_inset 
14553
14554  summarizes the information transmitted in a reply.
14555  Like an acknowledgement, most of the information is simply echoed from
14556  the get request.
14557  The initiator and target are obtained directly from the get request, but
14558  are swapped in generating the acknowledgement.
14559  The only new information in the acknowledgement are the manipulated length
14560  and the data, which are determined as the get request is satisfied.
14561 \layout Standard
14562
14563
14564 \begin_inset Float table
14565 placement htbp
14566 wide false
14567 collapsed false
14568
14569 \layout Caption
14570
14571 Information Passed in a Reply
14572 \begin_inset LatexCommand \label{tab:reply-wire}
14573
14574 \end_inset 
14575
14576
14577 \layout Standard
14578
14579
14580 \begin_inset ERT
14581 status Collapsed
14582
14583 \layout Standard
14584
14585 \backslash 
14586 medskip  
14587 \end_inset 
14588
14589
14590 \layout Standard
14591 \align center 
14592
14593 \size small 
14594
14595 \begin_inset  Tabular
14596 <lyxtabular version="3" rows="11" columns="4">
14597 <features firstHeadEmpty="true">
14598 <column alignment="left" valignment="top" width="0pt">
14599 <column alignment="left" valignment="top" width="0pt">
14600 <column alignment="left" valignment="top" width="0pt">
14601 <column alignment="left" valignment="top" width="0pt">
14602 <row bottomline="true">
14603 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14604 \begin_inset Text
14605
14606 \layout Standard
14607
14608
14609 \series bold 
14610 Information
14611 \series default 
14612  
14613 \end_inset 
14614 </cell>
14615 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14616 \begin_inset Text
14617
14618 \layout Standard
14619
14620
14621 \series bold 
14622 Type
14623 \end_inset 
14624 </cell>
14625 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14626 \begin_inset Text
14627
14628 \layout Standard
14629
14630
14631 \series bold 
14632 Put Information 
14633 \end_inset 
14634 </cell>
14635 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14636 \begin_inset Text
14637
14638 \layout Standard
14639
14640
14641 \series bold 
14642 Notes 
14643 \end_inset 
14644 </cell>
14645 </row>
14646 <row>
14647 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14648 \begin_inset Text
14649
14650 \layout Standard
14651
14652 operation 
14653 \end_inset 
14654 </cell>
14655 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14656 \begin_inset Text
14657
14658 \layout Standard
14659
14660
14661 \family typewriter 
14662 int
14663 \family default 
14664  
14665 \end_inset 
14666 </cell>
14667 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14668 \begin_inset Text
14669
14670 \layout Standard
14671
14672 \end_inset 
14673 </cell>
14674 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14675 \begin_inset Text
14676
14677 \layout Standard
14678
14679 indicates an acknowledgement 
14680 \end_inset 
14681 </cell>
14682 </row>
14683 <row>
14684 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14685 \begin_inset Text
14686
14687 \layout Standard
14688
14689 initiator 
14690 \end_inset 
14691 </cell>
14692 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14693 \begin_inset Text
14694
14695 \layout Standard
14696
14697
14698 \family typewriter 
14699 ptl_process_id_t 
14700 \end_inset 
14701 </cell>
14702 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14703 \begin_inset Text
14704
14705 \layout Standard
14706
14707 target 
14708 \end_inset 
14709 </cell>
14710 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14711 \begin_inset Text
14712
14713 \layout Standard
14714
14715 \end_inset 
14716 </cell>
14717 </row>
14718 <row>
14719 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14720 \begin_inset Text
14721
14722 \layout Standard
14723
14724 target 
14725 \end_inset 
14726 </cell>
14727 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14728 \begin_inset Text
14729
14730 \layout Standard
14731
14732
14733 \family typewriter 
14734 ptl_process_id_t 
14735 \end_inset 
14736 </cell>
14737 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14738 \begin_inset Text
14739
14740 \layout Standard
14741
14742 initiator 
14743 \end_inset 
14744 </cell>
14745 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14746 \begin_inset Text
14747
14748 \layout Standard
14749
14750 \end_inset 
14751 </cell>
14752 </row>
14753 <row>
14754 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14755 \begin_inset Text
14756
14757 \layout Standard
14758
14759 portal index 
14760 \end_inset 
14761 </cell>
14762 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14763 \begin_inset Text
14764
14765 \layout Standard
14766
14767
14768 \family typewriter 
14769 ptl_pt_index_t 
14770 \end_inset 
14771 </cell>
14772 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
14773 \begin_inset Text
14774
14775 \layout Standard
14776
14777 portal index 
14778 \end_inset 
14779 </cell>
14780 <cell alignment="right" valignment="top" bottomline="true" usebox="none">
14781 \begin_inset Text
14782
14783 \layout Standard
14784
14785 echo 
14786 \end_inset 
14787 </cell>
14788 </row>
14789 <row>
14790 <cell alignment="left" valignment="top" usebox="none">
14791 \begin_inset Text
14792
14793 \layout Standard
14794
14795 match bits 
14796 \end_inset 
14797 </cell>
14798 <cell alignment="right" valignment="top" usebox="none">
14799 \begin_inset Text
14800
14801 \layout Standard
14802
14803
14804 \family typewriter 
14805 ptl_match_bits_t 
14806 \end_inset 
14807 </cell>
14808 <cell alignment="left" valignment="top" usebox="none">
14809 \begin_inset Text
14810
14811 \layout Standard
14812
14813 match bits 
14814 \end_inset 
14815 </cell>
14816 <cell alignment="right" valignment="top" usebox="none">
14817 \begin_inset Text
14818
14819 \layout Standard
14820
14821 echo 
14822 \end_inset 
14823 </cell>
14824 </row>
14825 <row>
14826 <cell alignment="left" valignment="top" usebox="none">
14827 \begin_inset Text
14828
14829 \layout Standard
14830
14831 offset 
14832 \end_inset 
14833 </cell>
14834 <cell alignment="right" valignment="top" usebox="none">
14835 \begin_inset Text
14836
14837 \layout Standard
14838
14839
14840 \family typewriter 
14841 ptl_size_t
14842 \family default 
14843  
14844 \end_inset 
14845 </cell>
14846 <cell alignment="left" valignment="top" usebox="none">
14847 \begin_inset Text
14848
14849 \layout Standard
14850
14851 offset 
14852 \end_inset 
14853 </cell>
14854 <cell alignment="right" valignment="top" usebox="none">
14855 \begin_inset Text
14856
14857 \layout Standard
14858
14859 echo 
14860 \end_inset 
14861 </cell>
14862 </row>
14863 <row>
14864 <cell alignment="left" valignment="top" usebox="none">
14865 \begin_inset Text
14866
14867 \layout Standard
14868
14869 memory desc 
14870 \end_inset 
14871 </cell>
14872 <cell alignment="right" valignment="top" usebox="none">
14873 \begin_inset Text
14874
14875 \layout Standard
14876
14877
14878 \family typewriter 
14879 ptl_handle_md_t
14880 \family default 
14881  
14882 \end_inset 
14883 </cell>
14884 <cell alignment="left" valignment="top" usebox="none">
14885 \begin_inset Text
14886
14887 \layout Standard
14888
14889 memory desc 
14890 \end_inset 
14891 </cell>
14892 <cell alignment="right" valignment="top" usebox="none">
14893 \begin_inset Text
14894
14895 \layout Standard
14896
14897 echo 
14898 \end_inset 
14899 </cell>
14900 </row>
14901 <row>
14902 <cell alignment="left" valignment="top" usebox="none">
14903 \begin_inset Text
14904
14905 \layout Standard
14906
14907 requested length 
14908 \end_inset 
14909 </cell>
14910 <cell alignment="right" valignment="top" usebox="none">
14911 \begin_inset Text
14912
14913 \layout Standard
14914
14915
14916 \family typewriter 
14917 ptl_size_t
14918 \family default 
14919  
14920 \end_inset 
14921 </cell>
14922 <cell alignment="left" valignment="top" usebox="none">
14923 \begin_inset Text
14924
14925 \layout Standard
14926
14927 length 
14928 \end_inset 
14929 </cell>
14930 <cell alignment="right" valignment="top" usebox="none">
14931 \begin_inset Text
14932
14933 \layout Standard
14934
14935 echo 
14936 \end_inset 
14937 </cell>
14938 </row>
14939 <row>
14940 <cell alignment="left" valignment="top" usebox="none">
14941 \begin_inset Text
14942
14943 \layout Standard
14944
14945 manipulated length 
14946 \end_inset 
14947 </cell>
14948 <cell alignment="right" valignment="top" usebox="none">
14949 \begin_inset Text
14950
14951 \layout Standard
14952
14953
14954 \family typewriter 
14955 ptl_size_t
14956 \family default 
14957  
14958 \end_inset 
14959 </cell>
14960 <cell alignment="left" valignment="top" usebox="none">
14961 \begin_inset Text
14962
14963 \layout Standard
14964
14965 \end_inset 
14966 </cell>
14967 <cell alignment="right" valignment="top" usebox="none">
14968 \begin_inset Text
14969
14970 \layout Standard
14971
14972 obtained from the operation 
14973 \end_inset 
14974 </cell>
14975 </row>
14976 <row>
14977 <cell alignment="left" valignment="top" usebox="none">
14978 \begin_inset Text
14979
14980 \layout Standard
14981
14982 data 
14983 \end_inset 
14984 </cell>
14985 <cell alignment="right" valignment="top" usebox="none">
14986 \begin_inset Text
14987
14988 \layout Standard
14989
14990
14991 \emph on 
14992 bytes
14993 \end_inset 
14994 </cell>
14995 <cell alignment="left" valignment="top" usebox="none">
14996 \begin_inset Text
14997
14998 \layout Standard
14999
15000 \end_inset 
15001 </cell>
15002 <cell alignment="right" valignment="top" usebox="none">
15003 \begin_inset Text
15004
15005 \layout Standard
15006
15007 obtained from the operation 
15008 \end_inset 
15009 </cell>
15010 </row>
15011 </lyxtabular>
15012
15013 \end_inset 
15014
15015
15016 \end_inset 
15017
15018
15019 \layout Section
15020
15021 Receiving Messages
15022 \begin_inset LatexCommand \label{sec:receiving}
15023
15024 \end_inset 
15025
15026
15027 \layout Standard
15028
15029 When an incoming message arrives on a network interface, the communication
15030  system first checks that the target process identified in the request is
15031  a valid process that has initialized the network interface (i.e., that the
15032  target process has a valid Portal table).
15033  If this test fails, the communication system discards the message and increment
15034 s the dropped message count for the interface.
15035  The remainder of the processing depends on the type of the incoming message.
15036  Put and get messages are subject to access control checks and translation
15037  (searching a match list), while acknowledgement and reply messages bypass
15038  the access control checks and the translation step.
15039 \layout Standard
15040
15041 Acknowledgement messages include a handle for the memory descriptor used
15042  in the original 
15043 \emph on 
15044 PtlPut
15045 \emph default 
15046  operation.
15047  This memory descriptor will identify the event queue where the event should
15048  be recorded.
15049  Upon receipt of an acknowledgement, the runtime system only needs to confirm
15050  that the memory descriptor and event queue still exist and that there is
15051  space for another event.
15052  Should the any of these conditions fail,  the message is simply discarded
15053  and the dropped message count for the interface is incremented.
15054  Otherwise, the system builds an acknowledgement event from the information
15055  in the acknowledgement message and adds it to the event queue.
15056 \layout Standard
15057
15058 Reception of reply messages is also relatively straightforward.
15059  Each reply message includes a handle for a memory descriptor.
15060  If this descriptor exists, it is used to receive the message.
15061  A reply message will be dropped if the memory descriptor identified in
15062  the request doesn't exist.
15063  In either of this case, the dropped message count for the interface is
15064  incremented.
15065  These are the only reasons for dropping reply messages.
15066  Every memory descriptor accepts and truncates incoming reply messages,
15067  eliminating the other potential reasons for rejecting a reply message.
15068 \layout Standard
15069
15070 The critical step in processing an incoming put or get request involves
15071  mapping the request to a memory descriptor.
15072  This step starts by using the Portal index in the incoming request to identify
15073  a list of match entries.
15074  This list of match entries is searched in order until a match entry is
15075  found whose match criteria matches the match bits in the incoming request
15076  and whose memory descriptor accepts the request.
15077 \layout Standard
15078
15079 Because acknowledge and reply messages are generated in response to requests
15080  made by the process receiving these messages, the checks performed by the
15081  runtime system for acknowledgements and replies are minimal.
15082  In contrast, put and get messages are generated by remote processes and
15083  the checks performed for these messages are more extensive.
15084  Incoming put or get messages may be rejected because: 
15085 \layout Itemize
15086
15087 the Portal index supplied in the request is not valid; 
15088 \layout Itemize
15089
15090 the cookie supplied in the request is not a valid access control entry;
15091  
15092 \layout Itemize
15093
15094 the access control entry identified by the cookie does not match the identifier
15095  of the requesting process; 
15096 \layout Itemize
15097
15098 the access control entry identified by the access control entry does not
15099  match the Portal index supplied in the request; or 
15100 \layout Itemize
15101
15102 the match bits supplied in the request do not match any of the match entries
15103  with a memory descriptor that accepts the request.
15104  
15105 \layout Standard
15106
15107 In all cases, if the message is rejected, the incoming message is discarded
15108  and the dropped message count for the interface is incremented.
15109 \layout Standard
15110
15111 A memory descriptor may reject an incoming request for any of the following
15112  reasons: 
15113 \layout Itemize
15114
15115 the 
15116 \family typewriter 
15117 PTL_MD_PUT
15118 \family default 
15119  or 
15120 \family typewriter 
15121 PTL_MD_GET
15122 \family default 
15123  option has not been enabled and the operation is put or get, respectively;
15124  
15125 \layout Itemize
15126
15127 the length specified in the request is too long for the memory descriptor
15128  and the 
15129 \family typewriter 
15130 PTL_MD_TRUNCATE
15131 \family default 
15132  option has not been enabled.
15133 \layout Chapter
15134
15135 Examples
15136 \begin_inset LatexCommand \label{sec:examples}
15137
15138 \end_inset 
15139
15140
15141 \layout Comment
15142
15143 The examples presented in this chapter have not been updated to reflect
15144  the current API.
15145 \layout Standard
15146
15147 In this section we present several example to illustrate expected usage
15148  patterns for the Portals 3.2 API.
15149  The first example describes how to implement parallel servers using the
15150  features of the Portals 3.2 API.
15151  This example covers the access control list and the use of remote managed
15152  offsets.
15153  The second example presents an approach to dealing with dropped requests.
15154  This example covers aspects of match lists and memory descriptors.
15155  The final example covers message reception in MPI.
15156  This example illustrates more sophisticated uses of matching and a procedure
15157  to update a memory descriptor.
15158 \layout Section
15159
15160 Parallel File Servers
15161 \begin_inset LatexCommand \label{sec:expfs}
15162
15163 \end_inset 
15164
15165
15166 \layout Standard
15167
15168 Figure\SpecialChar ~
15169
15170 \begin_inset LatexCommand \ref{fig:file}
15171
15172 \end_inset 
15173
15174  illustrates the logical structure of a parallel file server.
15175  In this case, the parallel server consists of four servers that stripe
15176  application data across four disks.
15177  We would like to present applications with the illusion that the file server
15178  is a single entity.
15179  We will assume that all of the processes that constitute the parallel server
15180  have the same user id.
15181 \layout Standard
15182
15183
15184 \begin_inset Float figure
15185 placement htbp
15186 wide false
15187 collapsed false
15188
15189 \layout Standard
15190 \align center 
15191
15192 \begin_inset Graphics FormatVersion 1
15193         filename file.eps
15194         display color
15195         size_type 0
15196         rotateOrigin center
15197         lyxsize_type 1
15198         lyxwidth 196pt
15199         lyxheight 147pt
15200 \end_inset 
15201
15202
15203 \layout Caption
15204
15205 Parallel File Server
15206 \begin_inset LatexCommand \label{fig:file}
15207
15208 \end_inset 
15209
15210
15211 \end_inset 
15212
15213
15214 \layout Standard
15215
15216 When an application establishes a connection to the parallel file server,
15217  it will allocate a Portal and access control list entry for communicating
15218  with the server.
15219  The access control list entry will include the Portal and match any process
15220  in the parallel file server's, so all of the file server processes will
15221  have access to the portal.
15222  The Portal information and access control entry will be sent to the file
15223  server at this time.
15224  If the application and server need to have multiple, concurrent I/O operations,
15225  they can use additional portals or match entries to keep the operations
15226  from interfering with one another.
15227 \layout Standard
15228
15229 When an application initiates an I/O operation, it first builds a memory
15230  descriptor that describes the memory region involved in the operation.
15231  This memory descriptor will enable the appropriate operation (put for read
15232  operations and get for write operations) and enable the use of remote offsets
15233  (this lets the servers decide where their data should be placed in the
15234  memory region).
15235  After creating the memory descriptor and linking it into the appropriate
15236  Portal entry, the application sends a read or write request (using 
15237 \emph on 
15238 PtlPut
15239 \emph default 
15240 ) to one of the file server processes.
15241  The file server processes can then use put or get operations with the appropria
15242 te offsets to fill or retrieve the contents of the application's buffer.
15243  To know when the operation has completed, the application can add an event
15244  queue to the memory descriptor and add up the lengths of the remote operations
15245  until the sum is the size of the requested I/O operation.
15246 \layout Section
15247
15248 Dealing with Dropped Requests
15249 \begin_inset LatexCommand \label{sec:exdrop}
15250
15251 \end_inset 
15252
15253
15254 \layout Standard
15255
15256 If a process does not anticipate unexpected requests, they will be discarded.
15257  Applications using the Portals API can query the dropped count for the
15258  interface to determine the number of requests that have been dropped (see
15259  Section\SpecialChar ~
15260
15261 \begin_inset LatexCommand \ref{sec:nistatus}
15262
15263 \end_inset 
15264
15265 ).
15266  While this approach minimizes resource consumption, it does not provide
15267  information that might be critical in debugging the implementation of a
15268  higher level protocol.
15269 \layout Standard
15270
15271 To keep track of more information about dropped requests, we use a memory
15272  descriptor that truncates each incoming request to zero bytes and logs
15273  the 
15274 \begin_inset Quotes eld
15275 \end_inset 
15276
15277 dropped
15278 \begin_inset Quotes erd
15279 \end_inset 
15280
15281  operations in an event queue.
15282  Note that the operations are not dropped in the Portals sense, because
15283  the operation succeeds.
15284 \layout Standard
15285
15286 The following code fragment illustrates an implementation of this approach.
15287  In this case, we assume that a thread is launched to execute the function
15288  
15289 \family typewriter 
15290 watch_drop
15291 \family default 
15292 .
15293  This code starts by building an event queue to log truncated operations
15294  and a memory descriptor to truncate the incoming requests.
15295  This example only captures 
15296 \begin_inset Quotes eld
15297 \end_inset 
15298
15299 dropped
15300 \begin_inset Quotes erd
15301 \end_inset 
15302
15303  requests for a single portal.
15304  In a more realistic situation, the memory descriptor would be appended
15305  to the match list for every portal.
15306  We also assume that the thread is capable of keeping up with the 
15307 \begin_inset Quotes eld
15308 \end_inset 
15309
15310 dropped
15311 \begin_inset Quotes erd
15312 \end_inset 
15313
15314  requests.
15315  If this is not the case, we could use a finite threshold on the memory
15316  descriptor to capture the first few dropped requests.
15317 \layout LyX-Code
15318
15319
15320 \size small 
15321 #include <stdio.h>
15322 \newline 
15323 #include <stdlib.h>
15324 \newline 
15325 #include <portals.h>
15326 \newline 
15327
15328 \newline 
15329 #define DROP_SIZE 32       /* number of dropped requests to track */
15330 \newline 
15331
15332 \newline 
15333 int watch_drop( ptl_handle_ni_t ni, ptl_pt_index_t index ) {
15334 \newline 
15335     ptl_handle_eq_t drop_events;
15336 \newline 
15337     ptl_event_t event;
15338 \newline 
15339     ptl_handle_md_t drop_em;
15340 \newline 
15341     ptl_md_t drop_desc;
15342 \newline 
15343     ptl_process_id_t any_proc;
15344 \newline 
15345     ptl_handle_me_t match_any;
15346 \newline 
15347
15348 \newline 
15349     /* create the event queue */
15350 \newline 
15351     if( PtlEQAlloc(ni, DROP_SIZE, &drop_events) != PTL_OK ) {
15352 \newline 
15353         fprintf( stderr, "Couldn't create the event queue
15354 \backslash 
15355 n" );
15356 \newline 
15357         exit( 1 );
15358 \newline 
15359     }
15360 \newline 
15361
15362 \newline 
15363     /* build a match entry */
15364 \newline 
15365     any_proc.nid = PTL_ID_ANY;
15366 \newline 
15367     any_proc.pid = PTL_ID_ANY;
15368 \newline 
15369     PtlMEAttach( index, any_proc, 0, ~(ptl_match_bits_t)0, PTL_RETAIN,
15370 \newline 
15371                         &match_any );
15372 \newline 
15373
15374 \newline 
15375     /* create the memory descriptor */
15376 \newline 
15377     drop_desc.start = NULL;
15378 \newline 
15379     drop_desc.length = 0;
15380 \newline 
15381     drop_desc.threshold = PTL_MD_THRESH_INF;
15382 \newline 
15383     drop_desc.options = PTL_MD_OP_PUT | PTL_MD_OP_GET | PTL_MD_TRUNCATE;
15384 \newline 
15385     drop_desc.user_ptr = NULL;
15386 \newline 
15387     drop_desc.eventq = drop_events;
15388 \newline 
15389     if( PtlMDAttach(match_any, drop_desc, &drop_em) != PTL_OK ) {
15390 \newline 
15391         fprintf( stderr, "Couldn't create the memory descriptor
15392 \backslash 
15393 n" );
15394 \newline 
15395         exit( 1 );
15396 \newline 
15397     }
15398 \newline 
15399
15400 \newline 
15401     /* watch for "dropped" requests */
15402 \newline 
15403     while( 1 ) {
15404 \newline 
15405         if( PtlEQWait( drop_events, &event ) != PTL_OK ) break;
15406 \newline 
15407         fprintf( stderr, "Dropped request from gid = event.initiator.gid,
15408  event.initiator.rid );
15409 \newline 
15410     }
15411 \newline 
15412 }
15413 \layout Section
15414
15415 Message Transmission in MPI
15416 \begin_inset LatexCommand \label{sec:exmpi}
15417
15418 \end_inset 
15419
15420
15421 \layout Standard
15422
15423 We conclude this section with a fairly extensive example that describes
15424  an approach to implementing message transmission for MPI.
15425  Like many MPI implementations, we distinguish two message transmission
15426  protocols: a short message protocol and a long message protocol.
15427  We use the constant 
15428 \family typewriter 
15429 MPI_LONG_LENGTH
15430 \family default 
15431  to determine the size of a long message.
15432 \layout Standard
15433
15434 For small messages, the sender simply sends the message and presumes that
15435  the message will be received (i.e., the receiver has allocated a memory region
15436  to receive the message body).
15437  For large messages, the sender also sends the message, but does not presume
15438  that the message body will be saved.
15439  Instead, the sender builds a memory descriptor for the message and enables
15440  get operations on this descriptor.
15441  If the target does not save the body of the message, it will record an
15442  event for the put operation.
15443  When the process later issues a matching MPI receive, it will perform a
15444  get operation to retrieve the body of the message.
15445 \layout Standard
15446
15447 To facilitate receive side matching based on the protocol, we use the most
15448  significant bit in the match bits to indicate the protocol: 1 for long
15449  messages and 0 for short messages.
15450 \layout Standard
15451
15452 The following code presents a function that implements the send side of
15453  the protocol.
15454  The global variable 
15455 \family typewriter 
15456 EndGet
15457 \family default 
15458  is the last match entry attached to the Portal index used for posting long
15459  messages.
15460  This entry does not match any incoming requests (i.e., the memory descriptor
15461  rejects all get operations) and is built during initialization of the MPI
15462  library.
15463  The other global variable, 
15464 \family typewriter 
15465 MPI_NI
15466 \family default 
15467 , is a handle for the network interface used by the MPI implementation.
15468 \layout LyX-Code
15469
15470
15471 \size small 
15472 extern ptl_handle_me_t EndGet;
15473 \newline 
15474 extern ptl_handle_ni_t MPI_NI;
15475 \newline 
15476
15477 \newline 
15478 void MPIsend( void *buf, ptl_size_t len, void *data, ptl_handle_eq_t eventq,
15479 \newline 
15480                     ptl_process_id target, ptl_match_bits_t match ) 
15481 \newline 
15482 {
15483 \newline 
15484     ptl_handle_md_t send_handle;
15485 \newline 
15486     ptl_md_t mem_desc;
15487 \newline 
15488     ptl_ack_req_t want_ack;
15489 \newline 
15490
15491 \newline 
15492     mem_desc.start = buf;
15493 \newline 
15494     mem_desc.length = len;
15495 \newline 
15496     mem_desc.threshold = 1;
15497 \newline 
15498     mem_desc.options = PTL_MD_GET_OP;
15499 \newline 
15500     mem_desc.user_ptr = data;
15501 \newline 
15502     mem_desc.eventq = eventq;
15503 \newline 
15504
15505 \newline 
15506     if( len >= MPI_LONG_LENGTH ) {
15507 \newline 
15508         ptl_handle_me_t me_handle;
15509 \newline 
15510
15511 \newline 
15512         /* add a match entry to the end of the get list */
15513 \newline 
15514         PtlMEInsert( target, match, 0, PTL_UNLINK, PTL_INS_BEFORE, EndGet,
15515  &me_handle );
15516 \newline 
15517         PtlMDAttach( me_handle, mem_desc, PTL_UNLINK, NULL );
15518 \newline 
15519
15520 \newline 
15521         /* we want an ack for long messages */
15522 \newline 
15523         want_ack = PTL_ACK_REQ;
15524 \newline 
15525
15526 \newline 
15527         /* set the protocol bit to indicate that this is a long message
15528  */
15529 \newline 
15530         match |= 1<<63;
15531 \newline 
15532     } else {
15533 \newline 
15534         /* we don't want an ack for short messages */
15535 \newline 
15536         want_ack = PTL_ACK_REQ;
15537 \newline 
15538
15539 \newline 
15540         /* set the protocol bit to indicate that this is a short message
15541  */
15542 \newline 
15543         match &= ~(1<<63);
15544 \newline 
15545     }
15546 \newline 
15547
15548 \newline 
15549    /* create a memory descriptor and send it */
15550 \newline 
15551    PtlMDBind( MPI_NI, mem_desc, &send_handle );
15552 \newline 
15553    PtlPut( send_handle, want_ack, target, MPI_SEND_PINDEX, MPI_AINDEX, match,
15554  0 );
15555 \newline 
15556 }
15557 \layout Standard
15558
15559 The 
15560 \emph on 
15561 MPISend
15562 \emph default 
15563  function returns as soon as the message has been scheduled for transmission.
15564  The event queue argument, 
15565 \family typewriter 
15566 eventq
15567 \family default 
15568 , can be used to determine the disposition of the message.
15569  Assuming that 
15570 \family typewriter 
15571 eventq
15572 \family default 
15573  is not 
15574 \family typewriter 
15575 PTL_EQ_NONE
15576 \family default 
15577 , a 
15578 \family typewriter 
15579 PTL_EVENT_SENT
15580 \family default 
15581  event will be recorded for each message as the message is transmitted.
15582  For small messages, this is the only event that will be recorded in 
15583 \family typewriter 
15584 eventq
15585 \family default 
15586 .
15587  In contrast, long messages include an explicit request for an acknowledgement.
15588  If the 
15589 \family typewriter 
15590 target
15591 \family default 
15592  process has posted a matching receive, the acknowledgement will be sent
15593  as the message is received.
15594  If a matching receive has not been posted, the message will be discarded
15595  and no acknowledgement will be sent.
15596  When the 
15597 \family typewriter 
15598 target
15599 \family default 
15600  process later issues a matching receive, the receive will be translated
15601  into a get operation and a 
15602 \family typewriter 
15603 PTL_EVENT_GET
15604 \family default 
15605  event will be recorded in 
15606 \family typewriter 
15607 eventq
15608 \family default 
15609 .
15610 \layout Standard
15611
15612 Figure\SpecialChar ~
15613
15614 \begin_inset LatexCommand \ref{fig:mpi}
15615
15616 \end_inset 
15617
15618  illustrates the organization of the match list used for receiving MPI messages.
15619  The initial entries (not shown in this figure) would be used to match the
15620  MPI receives that have been preposted by the application.
15621  The preposted receives are followed by a match entry, 
15622 \emph on 
15623 RcvMark
15624 \emph default 
15625 , that marks the boundary between preposted receives and the memory descriptors
15626  used for 
15627 \begin_inset Quotes eld
15628 \end_inset 
15629
15630 unexpected
15631 \begin_inset Quotes erd
15632 \end_inset 
15633
15634  messages.
15635  The 
15636 \emph on 
15637 RcvMark
15638 \emph default 
15639  entry is followed by a small collection of match entries that match unexpected
15640  
15641 \begin_inset Quotes eld
15642 \end_inset 
15643
15644 short
15645 \begin_inset Quotes erd
15646 \end_inset 
15647
15648  messages, i.e., messages that have a 0 in the most significant bit of their
15649  match bits.
15650  The memory descriptors associated with these match entries will append
15651  the incoming message to the associated memory descriptor and record an
15652  event in an event queue for unexpected messages.
15653  The unexpected short message matching entries are followed by a match entry
15654  that will match messages that were not matched by the preceding match entries,
15655  i.e., the unexpected long messages.
15656  The memory descriptor associated with this match entry truncates the message
15657  body and records an event in the event queue for unexpected messages.
15658  Note that of the memory descriptors used for unexpected messages share
15659  a common event queue.
15660  This makes it possible to process the unexpected messages in the order
15661  in which they arrived, regardless of.
15662 \layout Standard
15663
15664
15665 \begin_inset Float figure
15666 placement htbp
15667 wide false
15668 collapsed false
15669
15670 \layout Standard
15671 \align center 
15672
15673 \begin_inset Graphics FormatVersion 1
15674         filename mpi.eps
15675         display color
15676         size_type 0
15677         rotateOrigin center
15678         lyxsize_type 1
15679         lyxwidth 389pt
15680         lyxheight 284pt
15681 \end_inset 
15682
15683
15684 \layout Caption
15685
15686 Message Reception in MPI
15687 \begin_inset LatexCommand \label{fig:mpi}
15688
15689 \end_inset 
15690
15691
15692 \end_inset 
15693
15694
15695 \layout Standard
15696
15697 When the local MPI process posts an MPI receive, we must first search the
15698  events unexpected message queue to see if a matching message has already
15699  arrived.
15700  If no matching message is found, a match entry for the receive is inserted
15701  before the 
15702 \emph on 
15703 RcvMark
15704 \emph default 
15705  entry--after the match entries for all of the previously posted receives
15706  and before the match entries for the unexpected messages.
15707  This ensures that preposted receives are matched in the order that they
15708  were posted (a requirement of MPI).
15709  
15710 \layout Standard
15711
15712 While this strategy respects the temporal semantics of MPI, it introduces
15713  a race condition: a matching message might arrive after the events in the
15714  unexpected message queue have been searched, but before the match entry
15715  for the receive has been inserted in the match list.
15716  
15717 \layout Standard
15718
15719 To avoid this race condition we start by setting the 
15720 \family typewriter 
15721 threshold
15722 \family default 
15723  of the memory descriptor to 0, making the descriptor inactive.
15724  We then insert the match entry into the match list and proceed to search
15725  the events in the unexpected message queue.
15726  A matching message that arrives as we are searching the unexpected message
15727  queue will not be accepted by the memory descriptor and, if not matched
15728  by an earlier match list element, will add an event to the unexpected message
15729  queue.
15730  After searching the events in the unexpected message queue, we update the
15731  memory descriptor, setting the threshold to 1 to activate the memory descriptor.
15732  This update is predicated by the condition that the unexpected message
15733  queue is empty.
15734  We repeat the process of searching the unexpected message queue until the
15735  update succeeds.
15736 \layout Standard
15737
15738 The following code fragment illustrates this approach.
15739  Because events must be removed from the unexpected message queue to be
15740  examined, this code fragment assumes the existence of a user managed event
15741  list, 
15742 \family typewriter 
15743 Rcvd
15744 \family default 
15745 , for the events that have already been removed from the unexpected message
15746  queue.
15747  In an effort to keep the example focused on the basic protocol, we have
15748  omitted the code that would be needed to manage the memory descriptors
15749  used for unexpected short messages.
15750  In particular, we simply leave messages in these descriptors until they
15751  are received by the application.
15752  In a robust implementation, we would introduce code to ensure that short
15753  unexpected messages are removed from these memory descriptors so that they
15754  can be re-used.
15755 \layout LyX-Code
15756
15757
15758 \size small 
15759 extern ptl_handle_eq_t UnexpQueue;
15760 \newline 
15761 extern ptl_handle_me_t RcvMark;
15762 \newline 
15763 extern ptl_handle_me_t ShortMatch;
15764 \newline 
15765
15766 \newline 
15767 typedef struct event_list_tag {
15768 \newline 
15769     ptl_event_t            event;
15770 \newline 
15771     struct event_list_tag* next;
15772 \newline 
15773 } event_list;
15774 \newline 
15775
15776 \newline 
15777 extern event_list Rcvd;
15778 \newline 
15779
15780 \newline 
15781 void AppendRcvd( ptl_event_t event )
15782 \newline 
15783 {
15784 \newline 
15785     /* append an event onto the Rcvd list */
15786 \newline 
15787 }
15788 \newline 
15789
15790 \newline 
15791 int SearchRcvd( void *buf, ptl_size_t len, ptl_process_id_t sender, ptl_match_bi
15792 ts_t match,
15793 \newline 
15794                        ptl_match_bits_t ignore, ptl_event_t *event )
15795 \newline 
15796 {
15797 \newline 
15798     /* Search the Rcvd event queue, looking for a message that matches the
15799  requested message.
15800 \newline 
15801      * If one is found, remove the event from the Rcvd list and return it.
15802  */
15803 \newline 
15804 }
15805 \newline 
15806
15807 \newline 
15808 typedef enum { RECEIVED, POSTED } receive_state;
15809 \newline 
15810
15811 \newline 
15812 receive_state CopyMsg( void *buf, ptl_size_t &length, ptl_event_t event,
15813  ptl_md_t md_buf )
15814 \newline 
15815 {
15816 \newline 
15817     ptl_md_t md_buf;
15818 \newline 
15819     ptl_handle_me_t me_handle;
15820 \newline 
15821
15822 \newline 
15823     if( event.rlength >= MPI_LONG_LENGTH ) {
15824 \newline 
15825         PtlMDBind( MPI_NI, md_buf, &md_handle );
15826 \newline 
15827         PtlGet( event.initiator, MPI_GET_PINDEX, 0, event.match_bits, MPI_AINDEX,
15828  md_handle );
15829 \newline 
15830         return POSTED;
15831 \newline 
15832     } else {
15833 \newline 
15834         /* copy the message */
15835 \newline 
15836         if( event.mlength < *length ) *length = event.mlength;
15837 \newline 
15838         memcpy( buf, (char*)event.md_desc.start+event.offset, *length );
15839 \newline 
15840         return RECEIVED;
15841 \newline 
15842     }
15843 \newline 
15844 }
15845 \newline 
15846
15847 \newline 
15848 receive_state MPIreceive( void *buf, ptl_size_t &len, void *MPI_data, ptl_handle
15849 _eq_t eventq, 
15850 \newline 
15851                            ptl_process_id_t sender, ptl_match_bits_t match,
15852  ptl_match_bits_t ignore )
15853 \newline 
15854 {
15855 \newline 
15856     ptl_md_t md_buf;
15857 \newline 
15858     ptl_handle_md_t md_handle;
15859 \newline 
15860     ptl_handle_me_t me_handle;
15861 \newline 
15862     ptl_event_t event;
15863 \newline 
15864
15865 \newline 
15866     /* build a memory descriptor for the receive */
15867 \newline 
15868     md_buf.start = buf;
15869 \newline 
15870     md_buf.length = *len;
15871 \newline 
15872     md_buf.threshold = 0;     /* temporarily disabled */
15873 \newline 
15874     md_buf.options = PTL_MD_PUT_OP;
15875 \newline 
15876     md_buf.user_ptr = MPI_data;
15877 \newline 
15878     md_buf.eventq = eventq;
15879 \newline 
15880
15881 \newline 
15882     /* see if we have already received the message */
15883 \newline 
15884     if( SearchRcvd(buf, len, sender, match, ignore, &event) )
15885 \newline 
15886          return CopyMsg( buf, len, event, md_buf );
15887 \newline 
15888
15889 \newline 
15890     /* create the match entry and attach the  memory descriptor */
15891 \newline 
15892     PtlMEInsert(sender, match, ignore, PTL_UNLINK, PTL_INS_BEFORE, RcvMark,
15893  &me_handle);
15894 \newline 
15895     PtlMDAttach( me_handle, md_buf, PTL_UNLINK, &md_handle );
15896 \newline 
15897
15898 \newline 
15899     md_buf.threshold = 1;
15900 \newline 
15901     do
15902 \newline 
15903         if( PtlEQGet( UnexpQueue, &event ) != PTL_EQ_EMPTY ) {
15904 \newline 
15905             if( MPIMatch(event, match, ignore, sender) ) {
15906 \newline 
15907                 return CopyMsg( buf, len, (char*)event.md_desc.start+event.offset,
15908  md_buf );
15909 \newline 
15910             } else {
15911 \newline 
15912                 AppendRcvd( event );
15913 \newline 
15914             }
15915 \newline 
15916         }
15917 \newline 
15918     while( PtlMDUpdate(md_handle, NULL, &md_buf, unexp_queue) == PTL_NOUPDATE
15919  );
15920 \newline 
15921     return POSTED;
15922 \newline 
15923 }
15924 \layout Chapter*
15925
15926 Acknowledgments
15927 \layout Standard
15928
15929 Several people have contributed to the philosophy, design, and implementation
15930  of the Portals message passing architecture as it has evolved.
15931  We acknowledge the following people for their contributions: Al Audette,
15932  Lee Ann Fisk, David Greenberg, Tramm Hudson, Gabi Istrail, Chu Jong, Mike
15933  Levenhagen, Jim Otto, Mark Sears, Lance Shuler, Mack Stallcup, Jeff VanDyke,
15934  Dave van Dresser, Lee Ward, and Stephen Wheat.
15935  
15936 \layout Standard
15937
15938
15939 \begin_inset LatexCommand \BibTeX[ieee]{portals3}
15940
15941 \end_inset 
15942
15943
15944 \the_end