root/opal/datatype/opal_datatype.h

INCLUDED FROM

DEFINITIONS

1. opal_datatype_is_committed
2. opal_datatype_is_overlapped
3. opal_datatype_is_valid
4. opal_datatype_is_predefined
5. opal_datatype_is_contiguous_memory_layout
6. opal_datatype_type_lb
7. opal_datatype_type_ub
8. opal_datatype_type_size
9. opal_datatype_type_extent
10. opal_datatype_get_extent
11. opal_datatype_get_true_extent
12. opal_datatype_span

   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   2 /*
   3  * Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana
   4  *                         University Research and Technology
   5  *                         Corporation.  All rights reserved.
   6  * Copyright (c) 2004-2017 The University of Tennessee and The University
   7  *                         of Tennessee Research Foundation.  All rights
   8  *                         reserved.
   9  * Copyright (c) 2004-2006 High Performance Computing Center Stuttgart,
  10  *                         University of Stuttgart.  All rights reserved.
  11  * Copyright (c) 2004-2006 The Regents of the University of California.
  12  *                         All rights reserved.
  13  * Copyright (c) 2007-2013 Los Alamos National Security, LLC.  All rights
  14  *                         reserved.
  15  * Copyright (c) 2009      Sun Microsystems, Inc.  All rights reserved.
  16  * Copyright (c) 2009      Oak Ridge National Labs.  All rights reserved.
  17  * Copyright (c) 2017-2018 Research Organization for Information Science
  18  *                         and Technology (RIST). All rights reserved.
  19  * Copyright (c) 2018      Triad National Security, LLC. All rights
  20  *                         reserved.
  21  * Copyright (c) 2018      FUJITSU LIMITED.  All rights reserved.
  22  * $COPYRIGHT$
  23  *
  24  * Additional copyrights may follow
  25  *
  26  * $HEADER$
  27  */
  28 
  29 /**
  30  * opal_datatype_t interface for OPAL internal data type representation
  31  *
  32  * opal_datatype_t is a class which represents contiguous or
  33  * non-contiguous data together with constituent type-related
  34  * information.
  35  */
  36 
  37 #ifndef OPAL_DATATYPE_H_HAS_BEEN_INCLUDED
  38 #define OPAL_DATATYPE_H_HAS_BEEN_INCLUDED
  39 
  40 #include "opal_config.h"
  41 
  42 #include <stddef.h>
  43 
  44 #include "opal/class/opal_object.h"
  45 
  46 BEGIN_C_DECLS
  47 
  48 /*
  49  * If there are more basic datatypes than the number of bytes in the int type
  50  * the bdt_used field of the data description struct should be changed to long.
  51  *
  52  * This must match the same definition as in opal_datatype_internal.h
  53  */
  54 #if !defined(OPAL_DATATYPE_MAX_PREDEFINED)
  55 #define OPAL_DATATYPE_MAX_PREDEFINED 26
  56 #endif
  57 /*
  58  * No more than this number of _Basic_ datatypes in C/CPP or Fortran
  59  * are supported (in order to not change setup and usage of the predefined
  60  * datatypes).
  61  *
  62  * BEWARE: This constant should reflect whatever the OMPI-layer needs.
  63  */
  64 #define OPAL_DATATYPE_MAX_SUPPORTED  50
  65 
  66 
  67 /* flags for the datatypes. */
  68 #define OPAL_DATATYPE_FLAG_UNAVAILABLE   0x0001  /**< datatypes unavailable on the build (OS or compiler dependant) */
  69 #define OPAL_DATATYPE_FLAG_PREDEFINED    0x0002  /**< cannot be removed: initial and predefined datatypes */
  70 #define OPAL_DATATYPE_FLAG_COMMITTED     0x0004  /**< ready to be used for a send/recv operation */
  71 #define OPAL_DATATYPE_FLAG_OVERLAP       0x0008  /**< datatype is unpropper for a recv operation */
  72 #define OPAL_DATATYPE_FLAG_CONTIGUOUS    0x0010  /**< contiguous datatype */
  73 #define OPAL_DATATYPE_FLAG_NO_GAPS       0x0020  /**< no gaps around the datatype, aka OPAL_DATATYPE_FLAG_CONTIGUOUS and extent == size */
  74 #define OPAL_DATATYPE_FLAG_USER_LB       0x0040  /**< has a user defined LB */
  75 #define OPAL_DATATYPE_FLAG_USER_UB       0x0080  /**< has a user defined UB */
  76 #define OPAL_DATATYPE_FLAG_DATA          0x0100  /**< data or control structure */
  77 /*
  78  * We should make the difference here between the predefined contiguous and non contiguous
  79  * datatypes. The OPAL_DATATYPE_FLAG_BASIC is held by all predefined contiguous datatypes.
  80  */
  81 #define OPAL_DATATYPE_FLAG_BASIC         (OPAL_DATATYPE_FLAG_PREDEFINED | \
  82                                           OPAL_DATATYPE_FLAG_CONTIGUOUS | \
  83                                           OPAL_DATATYPE_FLAG_NO_GAPS |    \
  84                                           OPAL_DATATYPE_FLAG_DATA |       \
  85                                           OPAL_DATATYPE_FLAG_COMMITTED)
  86 
  87 /**
  88  * The number of supported entries in the data-type definition and the
  89  * associated type.
  90  */
  91 #define MAX_DT_COMPONENT_COUNT UINT_MAX
  92 typedef size_t opal_datatype_count_t;
  93 
  94 typedef union dt_elem_desc dt_elem_desc_t;
  95 
  96 struct dt_type_desc_t {
  97     opal_datatype_count_t  length;  /**< the maximum number of elements in the description array */
  98     opal_datatype_count_t  used;    /**< the number of used elements in the description array */
  99     dt_elem_desc_t*        desc;
 100 };
 101 typedef struct dt_type_desc_t dt_type_desc_t;
 102 
 103 
 104 /*
 105  * The datatype description.
 106  */
 107 struct opal_datatype_t {
 108     opal_object_t      super;    /**< basic superclass */
 109     uint16_t           flags;    /**< the flags */
 110     uint16_t           id;       /**< data id, normally the index in the data array. */
 111     uint32_t           bdt_used; /**< bitset of which basic datatypes are used in the data description */
 112     size_t             size;     /**< total size in bytes of the memory used by the data if
 113                                       the data is put on a contiguous buffer */
 114     ptrdiff_t          true_lb;  /**< the true lb of the data without user defined lb and ub */
 115     ptrdiff_t          true_ub;  /**< the true ub of the data without user defined lb and ub */
 116     ptrdiff_t          lb;       /**< lower bound in memory */
 117     ptrdiff_t          ub;       /**< upper bound in memory */
 118     /* --- cacheline 1 boundary (64 bytes) --- */
 119     size_t             nbElems;  /**< total number of elements inside the datatype */
 120     uint32_t           align;    /**< data should be aligned to */
 121     uint32_t           loops;    /**< number of loops on the iternal type stack */
 122 
 123     /* Attribute fields */
 124     char               name[OPAL_MAX_OBJECT_NAME];  /**< name of the datatype */
 125     dt_type_desc_t     desc;     /**< the data description */
 126     dt_type_desc_t     opt_desc; /**< short description of the data used when conversion is useless
 127                                       or in the send case (without conversion) */
 128 
 129     size_t             *ptypes;  /**< array of basic predefined types that facilitate the computing
 130                                       of the remote size in heterogeneous environments. The length of the
 131                                       array is dependent on the maximum number of predefined datatypes of
 132                                       all language interfaces (because Fortran is not known at the OPAL
 133                                       layer). This field should never be initialized in homogeneous
 134                                       environments */
 135     /* --- cacheline 5 boundary (320 bytes) was 32-36 bytes ago --- */
 136 
 137     /* size: 352, cachelines: 6, members: 15 */
 138     /* last cacheline: 28-32 bytes */
 139 };
 140 
 141 typedef struct opal_datatype_t opal_datatype_t;
 142 
 143 OPAL_DECLSPEC OBJ_CLASS_DECLARATION( opal_datatype_t );
 144 
 145 OPAL_DECLSPEC extern const opal_datatype_t* opal_datatype_basicDatatypes[OPAL_DATATYPE_MAX_PREDEFINED];
 146 OPAL_DECLSPEC extern const size_t opal_datatype_local_sizes[OPAL_DATATYPE_MAX_PREDEFINED];
 147 
 148 /* Local Architecture as provided by opal_arch_compute_local_id() */
 149 OPAL_DECLSPEC extern uint32_t opal_local_arch;
 150 
 151 /*
 152  * The OPAL-layer's Basic datatypes themselves.
 153  */
 154 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_empty;
 155 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_loop;
 156 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_end_loop;
 157 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_lb;
 158 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_ub;
 159 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_int1;       /* in bytes */
 160 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_int2;       /* in bytes */
 161 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_int4;       /* in bytes */
 162 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_int8;       /* in bytes */
 163 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_int16;      /* in bytes */
 164 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_uint1;      /* in bytes */
 165 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_uint2;      /* in bytes */
 166 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_uint4;      /* in bytes */
 167 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_uint8;      /* in bytes */
 168 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_uint16;     /* in bytes */
 169 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float2;     /* in bytes */
 170 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float4;     /* in bytes */
 171 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float8;     /* in bytes */
 172 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float12;    /* in bytes */
 173 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float16;    /* in bytes */
 174 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_short_float_complex;
 175 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_float_complex;
 176 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_double_complex;
 177 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_long_double_complex;
 178 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_bool;
 179 OPAL_DECLSPEC extern const opal_datatype_t opal_datatype_wchar;
 180 
 181 
 182 /*
 183  * Functions exported externally
 184  */
 185 int opal_datatype_register_params(void);
 186 OPAL_DECLSPEC int32_t opal_datatype_init( void );
 187 OPAL_DECLSPEC opal_datatype_t* opal_datatype_create( int32_t expectedSize );
 188 OPAL_DECLSPEC int32_t opal_datatype_create_desc( opal_datatype_t * datatype, int32_t expectedSize );
 189 OPAL_DECLSPEC int32_t opal_datatype_commit( opal_datatype_t * pData );
 190 OPAL_DECLSPEC int32_t opal_datatype_destroy( opal_datatype_t** );
 191 OPAL_DECLSPEC int32_t opal_datatype_is_monotonic( opal_datatype_t* type);
 192 
 193 static inline int32_t
 194 opal_datatype_is_committed( const opal_datatype_t* type )
 195 {
 196     return ((type->flags & OPAL_DATATYPE_FLAG_COMMITTED) == OPAL_DATATYPE_FLAG_COMMITTED);
 197 }
 198 
 199 static inline int32_t
 200 opal_datatype_is_overlapped( const opal_datatype_t* type )
 201 {
 202     return ((type->flags & OPAL_DATATYPE_FLAG_OVERLAP) == OPAL_DATATYPE_FLAG_OVERLAP);
 203 }
 204 
 205 static inline int32_t
 206 opal_datatype_is_valid( const opal_datatype_t* type )
 207 {
 208     return !((type->flags & OPAL_DATATYPE_FLAG_UNAVAILABLE) == OPAL_DATATYPE_FLAG_UNAVAILABLE);
 209 }
 210 
 211 static inline int32_t
 212 opal_datatype_is_predefined( const opal_datatype_t* type )
 213 {
 214     return (type->flags & OPAL_DATATYPE_FLAG_PREDEFINED);
 215 }
 216 
 217 /*
 218  * This function return true (1) if the datatype representation depending on the count
 219  * is contiguous in the memory. And false (0) otherwise.
 220  */
 221 static inline int32_t
 222 opal_datatype_is_contiguous_memory_layout( const opal_datatype_t* datatype, int32_t count )
 223 {
 224     if( !(datatype->flags & OPAL_DATATYPE_FLAG_CONTIGUOUS) ) return 0;
 225     if( (count == 1) || (datatype->flags & OPAL_DATATYPE_FLAG_NO_GAPS) ) return 1;
 226     return 0;
 227 }
 228 
 229 
 230 OPAL_DECLSPEC void opal_datatype_dump( const opal_datatype_t* pData );
 231 /* data creation functions */
 232 OPAL_DECLSPEC int32_t opal_datatype_clone( const opal_datatype_t * src_type, opal_datatype_t * dest_type );
 233 OPAL_DECLSPEC int32_t opal_datatype_create_contiguous( int count, const opal_datatype_t* oldType, opal_datatype_t** newType );
 234 OPAL_DECLSPEC int32_t opal_datatype_resize( opal_datatype_t* type, ptrdiff_t lb, ptrdiff_t extent );
 235 OPAL_DECLSPEC int32_t opal_datatype_add( opal_datatype_t* pdtBase, const opal_datatype_t* pdtAdd, size_t count,
 236                                          ptrdiff_t disp, ptrdiff_t extent );
 237 
 238 static inline int32_t
 239 opal_datatype_type_lb( const opal_datatype_t* pData, ptrdiff_t* disp )
 240 {
 241     *disp = pData->lb;
 242     return 0;
 243 }
 244 
 245 static inline int32_t
 246 opal_datatype_type_ub( const opal_datatype_t* pData, ptrdiff_t* disp )
 247 {
 248     *disp = pData->ub;
 249     return 0;
 250 }
 251 
 252 static inline int32_t
 253 opal_datatype_type_size( const opal_datatype_t* pData, size_t *size )
 254 {
 255     *size = pData->size;
 256     return 0;
 257 }
 258 
 259 static inline int32_t
 260 opal_datatype_type_extent( const opal_datatype_t* pData, ptrdiff_t* extent )
 261 {
 262     *extent = pData->ub - pData->lb;
 263     return 0;
 264 }
 265 
 266 static inline int32_t
 267 opal_datatype_get_extent( const opal_datatype_t* pData, ptrdiff_t* lb, ptrdiff_t* extent)
 268 {
 269     *lb = pData->lb; *extent = pData->ub - pData->lb;
 270     return 0;
 271 }
 272 
 273 static inline int32_t
 274 opal_datatype_get_true_extent( const opal_datatype_t* pData, ptrdiff_t* true_lb, ptrdiff_t* true_extent)
 275 {
 276     *true_lb = pData->true_lb;
 277     *true_extent = (pData->true_ub - pData->true_lb);
 278     return 0;
 279 }
 280 
 281 OPAL_DECLSPEC ssize_t
 282 opal_datatype_get_element_count( const opal_datatype_t* pData, size_t iSize );
 283 OPAL_DECLSPEC int32_t
 284 opal_datatype_set_element_count( const opal_datatype_t* pData, size_t count, size_t* length );
 285 OPAL_DECLSPEC int32_t
 286 opal_datatype_copy_content_same_ddt( const opal_datatype_t* pData, int32_t count,
 287                                      char* pDestBuf, char* pSrcBuf );
 288 
 289 OPAL_DECLSPEC int opal_datatype_compute_ptypes( opal_datatype_t* datatype );
 290 
 291 OPAL_DECLSPEC const opal_datatype_t*
 292 opal_datatype_match_size( int size, uint16_t datakind, uint16_t datalang );
 293 
 294 /*
 295  *
 296  */
 297 OPAL_DECLSPEC int32_t
 298 opal_datatype_sndrcv( void *sbuf, int32_t scount, const opal_datatype_t* sdtype, void *rbuf,
 299                       int32_t rcount, const opal_datatype_t* rdtype);
 300 
 301 /*
 302  *
 303  */
 304 OPAL_DECLSPEC int32_t
 305 opal_datatype_get_args( const opal_datatype_t* pData, int32_t which,
 306                         int32_t * ci, int32_t * i,
 307                         int32_t * ca, ptrdiff_t* a,
 308                         int32_t * cd, opal_datatype_t** d, int32_t * type);
 309 OPAL_DECLSPEC int32_t
 310 opal_datatype_set_args( opal_datatype_t* pData,
 311                         int32_t ci, int32_t ** i,
 312                         int32_t ca, ptrdiff_t* a,
 313                         int32_t cd, opal_datatype_t** d,int32_t type);
 314 OPAL_DECLSPEC int32_t
 315 opal_datatype_copy_args( const opal_datatype_t* source_data,
 316                          opal_datatype_t* dest_data );
 317 OPAL_DECLSPEC int32_t
 318 opal_datatype_release_args( opal_datatype_t* pData );
 319 
 320 /*
 321  *
 322  */
 323 OPAL_DECLSPEC size_t
 324 opal_datatype_pack_description_length( const opal_datatype_t* datatype );
 325 
 326 /*
 327  *
 328  */
 329 OPAL_DECLSPEC int
 330 opal_datatype_get_pack_description( opal_datatype_t* datatype,
 331                                     const void** packed_buffer );
 332 
 333 /*
 334  *
 335  */
 336 struct opal_proc_t;
 337 OPAL_DECLSPEC opal_datatype_t*
 338 opal_datatype_create_from_packed_description( void** packed_buffer,
 339                                               struct opal_proc_t* remote_processor );
 340 
 341 /* Compute the span in memory of count datatypes. This function help with temporary
 342  * memory allocations for receiving already typed data (such as those used for reduce
 343  * operations). This span is the distance between the minimum and the maximum byte
 344  * in the memory layout of count datatypes, or in other terms the memory needed to
 345  * allocate count times the datatype without the gap in the beginning and at the end.
 346  *
 347  * Returns: the memory span of count repetition of the datatype, and in the gap
 348  *          argument, the number of bytes of the gap at the beginning.
 349  */
 350 static inline ptrdiff_t
 351 opal_datatype_span( const opal_datatype_t* pData, int64_t count,
 352                     ptrdiff_t* gap)
 353 {
 354     if (OPAL_UNLIKELY(0 == pData->size) || (0 == count)) {
 355         *gap = 0;
 356         return 0;
 357     }
 358     *gap = pData->true_lb;
 359     ptrdiff_t extent = (pData->ub - pData->lb);
 360     ptrdiff_t true_extent = (pData->true_ub - pData->true_lb);
 361     return true_extent + (count - 1) * extent;
 362 }
 363 
 364 #if OPAL_ENABLE_DEBUG
 365 /*
 366  * Set a breakpoint to this function in your favorite debugger
 367  * to make it stop on all pack and unpack errors.
 368  */
 369 OPAL_DECLSPEC int
 370 opal_datatype_safeguard_pointer_debug_breakpoint( const void* actual_ptr, int length,
 371                                                   const void* initial_ptr,
 372                                                   const opal_datatype_t* pData,
 373                                                   int count );
 374 #endif  /* OPAL_ENABLE_DEBUG */
 375 
 376 END_C_DECLS
 377 #endif  /* OPAL_DATATYPE_H_HAS_BEEN_INCLUDED */