1 /* 2 * Copyright (C) by Argonne National Laboratory 3 * See COPYRIGHT in top-level directory 4 */ 5 6 #ifndef MPIR_INFO_H_INCLUDED 7 #define MPIR_INFO_H_INCLUDED 8 9 /* ------------------------------------------------------------------------- */ 10 /* Info */ 11 /*TInfoOverview.tex 12 13 'MPI_Info' provides a way to create a list of '(key,value)' pairs 14 where the 'key' and 'value' are both strings. Because many routines, both 15 in the MPI implementation and in related APIs such as the PMI process 16 management interface, require 'MPI_Info' arguments, we define a simple 17 structure for each 'MPI_Info' element. Elements are allocated by the 18 generic object allocator; the head element is always empty (no 'key' 19 or 'value' is defined on the head element). 20 21 For simplicity, we have not abstracted the info data structures; 22 routines that want to work with the linked list may do so directly. 23 Because the 'MPI_Info' type is a handle and not a pointer, an MPIR 24 routine is provided to handle the 25 deallocation of 'MPIR_Info' elements. See the implementation of 26 'MPI_Info_create' for how an Info type is allocated. 27 28 Thread Safety: 29 30 The info interface itself is not thread-robust. In particular, the routines 31 'MPI_INFO_GET_NKEYS' and 'MPI_INFO_GET_NTHKEY' assume that no other 32 thread modifies the info key. (If the info routines had the concept 33 of a next value, they would not be thread safe. As it stands, a user 34 must be careful if several threads have access to the same info object.) 35 Further, 'MPI_INFO_DUP', while not 36 explicitly advising implementers to be careful of one thread modifying the 37 'MPI_Info' structure while 'MPI_INFO_DUP' is copying it, requires that the 38 operation take place in a thread-safe manner. 39 There isn'' much that we can do about these cases. There are other cases 40 that must be handled. In particular, multiple threads are allowed to 41 update the same info value. Thus, all of the update routines must be thread 42 safe; the simple implementation used in the MPICH implementation uses locks. 43 Note that the 'MPI_Info_delete' call does not need a lock; the defintion of 44 thread-safety means that any order of the calls functions correctly; since 45 it invalid either to delete the same 'MPI_Info' twice or to modify an 46 'MPI_Info' that has been deleted, only one thread at a time can call 47 'MPI_Info_free' on any particular 'MPI_Info' value. 48 49 T*/ 50 /*S 51 MPIR_Info - Structure of an MPIR info 52 53 Notes: 54 There is no reference count because 'MPI_Info' values, unlike other MPI 55 objects, may be changed after they are passed to a routine without 56 changing the routine''s behavior. In other words, any routine that uses 57 an 'MPI_Info' object must make a copy or otherwise act on any info value 58 that it needs. 59 60 A linked list is used because the typical 'MPI_Info' list will be short 61 and a simple linked list is easy to implement and to maintain. Similarly, 62 a single structure rather than separate header and element structures are 63 defined for simplicity. No separate thread lock is provided because 64 info routines are not performance critical; they may use the single 65 critical section lock in the 'MPIR_Process' structure when they need a 66 thread lock. 67 68 This particular form of linked list (in particular, with this particular 69 choice of the first two members) is used because it allows us to use 70 the same routines to manage this list as are used to manage the 71 list of free objects (in the file 'src/util/mem/handlemem.c'). In 72 particular, if lock-free routines for updating a linked list are 73 provided, they can be used for managing the 'MPIR_Info' structure as well. 74 75 The MPI standard requires that keys can be no less that 32 characters and 76 no more than 255 characters. There is no mandated limit on the size 77 of values. 78 79 Module: 80 Info-DS 81 S*/ 82 struct MPIR_Info { 83 MPIR_OBJECT_HEADER; /* adds handle and ref_count fields */ 84 struct MPIR_Info *next; 85 char *key; 86 char *value; 87 }; 88 extern MPIR_Object_alloc_t MPIR_Info_mem; 89 /* Preallocated info objects */ 90 #define MPIR_INFO_N_BUILTIN 2 91 extern MPIR_Info MPIR_Info_builtin[MPIR_INFO_N_BUILTIN]; 92 extern MPIR_Info MPIR_Info_direct[]; 93 94 int MPIR_Info_get_impl(MPIR_Info * info_ptr, const char *key, int valuelen, char *value, int *flag); 95 void MPIR_Info_get_nkeys_impl(MPIR_Info * info_ptr, int *nkeys); 96 int MPIR_Info_get_nthkey_impl(MPIR_Info * info, int n, char *key); 97 void MPIR_Info_get_valuelen_impl(MPIR_Info * info_ptr, const char *key, int *valuelen, int *flag); 98 int MPIR_Info_set_impl(MPIR_Info * info_ptr, const char *key, const char *value); 99 int MPIR_Info_dup_impl(MPIR_Info * info_ptr, MPIR_Info ** new_info_ptr); 100 void MPIR_Info_free(MPIR_Info * info_ptr); 101 int MPIR_Info_alloc(MPIR_Info ** info_p_p); 102 103 #endif /* MPIR_INFO_H_INCLUDED */ 104