552c9ca5a0
WHAT: Open our low-level communication infrastructure by moving all necessary components (btl/rcache/allocator/mpool) down in OPAL All the components required for inter-process communications are currently deeply integrated in the OMPI layer. Several groups/institutions have express interest in having a more generic communication infrastructure, without all the OMPI layer dependencies. This communication layer should be made available at a different software level, available to all layers in the Open MPI software stack. As an example, our ORTE layer could replace the current OOB and instead use the BTL directly, gaining access to more reactive network interfaces than TCP. Similarly, external software libraries could take advantage of our highly optimized AM (active message) communication layer for their own purpose. UTK with support from Sandia, developped a version of Open MPI where the entire communication infrastucture has been moved down to OPAL (btl/rcache/allocator/mpool). Most of the moved components have been updated to match the new schema, with few exceptions (mainly BTLs where I have no way of compiling/testing them). Thus, the completion of this RFC is tied to being able to completing this move for all BTLs. For this we need help from the rest of the Open MPI community, especially those supporting some of the BTLs. A non-exhaustive list of BTLs that qualify here is: mx, portals4, scif, udapl, ugni, usnic. This commit was SVN r32317.
503 строки
19 KiB
C
503 строки
19 KiB
C
/* -*- C -*-
|
|
*
|
|
* Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
|
|
* University Research and Technology
|
|
* Corporation. All rights reserved.
|
|
* Copyright (c) 2004-2005 The University of Tennessee and The University
|
|
* of Tennessee Research Foundation. All rights
|
|
* reserved.
|
|
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
|
|
* University of Stuttgart. All rights reserved.
|
|
* Copyright (c) 2004-2005 The Regents of the University of California.
|
|
* All rights reserved.
|
|
* Copyright (c) 2012 Los Alamos National Security, Inc. All rights reserved.
|
|
* Copyright (c) 2014 Intel, Inc. All rights reserved.
|
|
* $COPYRIGHT$
|
|
*
|
|
* Additional copyrights may follow
|
|
*
|
|
* $HEADER$
|
|
*/
|
|
/**
|
|
* @file
|
|
*
|
|
* Data packing subsystem.
|
|
*/
|
|
|
|
#ifndef OPAL_DSS_H_
|
|
#define OPAL_DSS_H_
|
|
|
|
#include "opal_config.h"
|
|
|
|
#include "opal/dss/dss_types.h"
|
|
|
|
BEGIN_C_DECLS
|
|
|
|
/* A non-API function for something that happens in a number
|
|
* of places throughout the code base - loading a value into
|
|
* an opal_value_t structure
|
|
*/
|
|
OPAL_DECLSPEC int opal_value_load(opal_value_t *kv,
|
|
void *data, opal_data_type_t type);
|
|
OPAL_DECLSPEC int opal_value_unload(opal_value_t *kv,
|
|
void **data, opal_data_type_t type);
|
|
|
|
/**
|
|
* Top-level interface function to pack one or more values into a
|
|
* buffer.
|
|
*
|
|
* The pack function packs one or more values of a specified type into
|
|
* the specified buffer. The buffer must have already been
|
|
* initialized via an OBJ_NEW or OBJ_CONSTRUCT call - otherwise, the
|
|
* pack_value function will return an error. Providing an unsupported
|
|
* type flag will likewise be reported as an error.
|
|
*
|
|
* Note that any data to be packed that is not hard type cast (i.e.,
|
|
* not type cast to a specific size) may lose precision when unpacked
|
|
* by a non-homogeneous recipient. The DSS will do its best to deal
|
|
* with heterogeneity issues between the packer and unpacker in such
|
|
* cases. Sending a number larger than can be handled by the recipient
|
|
* will return an error code (generated by the DSS upon unpacking) via
|
|
* the RML upon transmission - the DSS cannot detect such errors
|
|
* during packing.
|
|
*
|
|
* @param *buffer A pointer to the buffer into which the value is to
|
|
* be packed.
|
|
*
|
|
* @param *src A void* pointer to the data that is to be packed. Note
|
|
* that strings are to be passed as (char **) - i.e., the caller must
|
|
* pass the address of the pointer to the string as the void*. This
|
|
* allows the DSS to use a single interface function, but still allow
|
|
* the caller to pass multiple strings in a single call.
|
|
*
|
|
* @param num A size_t value indicating the number of values that are
|
|
* to be packed, beginning at the location pointed to by src. A string
|
|
* value is counted as a single value regardless of length. The values
|
|
* must be contiguous in memory. Arrays of pointers (e.g., string
|
|
* arrays) should be contiguous, although (obviously) the data pointed
|
|
* to need not be contiguous across array entries.
|
|
*
|
|
* @param type The type of the data to be packed - must be one of the
|
|
* DSS defined data types.
|
|
*
|
|
* @retval OPAL_SUCCESS The data was packed as requested.
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate OPAL error code indicating the
|
|
* problem encountered. This error code should be handled
|
|
* appropriately.
|
|
*
|
|
* @code
|
|
* opal_buffer_t *buffer;
|
|
* int32_t src;
|
|
*
|
|
* status_code = opal_dss.pack(buffer, &src, 1, OPAL_INT32);
|
|
* @endcode
|
|
*/
|
|
typedef int (*opal_dss_pack_fn_t)(opal_buffer_t *buffer, const void *src,
|
|
int32_t num_values,
|
|
opal_data_type_t type);
|
|
|
|
/**
|
|
* Unpack values from a buffer.
|
|
*
|
|
* The unpack function unpacks the next value (or values) of a
|
|
* specified type from the specified buffer.
|
|
*
|
|
* The buffer must have already been initialized via an OBJ_NEW or
|
|
* OBJ_CONSTRUCT call (and assumedly filled with some data) -
|
|
* otherwise, the unpack_value function will return an
|
|
* error. Providing an unsupported type flag will likewise be reported
|
|
* as an error, as will specifying a data type that DOES NOT match the
|
|
* type of the next item in the buffer. An attempt to read beyond the
|
|
* end of the stored data held in the buffer will also return an
|
|
* error.
|
|
*
|
|
* NOTE: it is possible for the buffer to be corrupted and that
|
|
* the DSS will *think* there is a proper variable type at the
|
|
* beginning of an unpack region - but that the value is bogus (e.g., just
|
|
* a byte field in a string array that so happens to have a value that
|
|
* matches the specified data type flag). Therefore, the data type error check
|
|
* is NOT completely safe. This is true for ALL unpack functions.
|
|
*
|
|
*
|
|
* Unpacking values is a "destructive" process - i.e., the values are
|
|
* removed from the buffer, thus reducing the buffer size. It is
|
|
* therefore not possible for the caller to re-unpack a value from the
|
|
* same buffer.
|
|
*
|
|
* Warning: The caller is responsible for providing adequate memory
|
|
* storage for the requested data. The opal_dss_peek() function is
|
|
* provided to assist in meeting this requirement. As noted below, the user
|
|
* must provide a parameter indicating the maximum number of values that
|
|
* can be unpacked into the allocated memory. If more values exist in the
|
|
* buffer than can fit into the memory storage, then the dss will unpack
|
|
* what it can fit into that location and return an error code indicating
|
|
* that the buffer was only partially unpacked.
|
|
*
|
|
* Note that any data that was not hard type cast (i.e., not type cast
|
|
* to a specific size) when packed may lose precision when unpacked by
|
|
* a non-homogeneous recipient. The DSS will do its best to deal with
|
|
* heterogeneity issues between the packer and unpacker in such
|
|
* cases. Sending a number larger than can be handled by the recipient
|
|
* will return an error code (generated by the DSS upon unpacking) via
|
|
* the RML upon transmission - the DSS cannot detect such errors
|
|
* during packing.
|
|
*
|
|
* @param *buffer A pointer to the buffer from which the value will be
|
|
* extracted.
|
|
*
|
|
* @param *dest A void* pointer to the memory location into which the
|
|
* data is to be stored. Note that these values will be stored
|
|
* contiguously in memory. For strings, this pointer must be to (char
|
|
* **) to provide a means of supporting multiple string
|
|
* operations. The DSS unpack function will allocate memory for each
|
|
* string in the array - the caller must only provide adequate memory
|
|
* for the array of pointers.
|
|
*
|
|
* @param *num A pointer to a int32_t value indicating the maximum
|
|
* number of values that are to be unpacked, beginning at the location
|
|
* pointed to by src. This is provided to help protect the caller from
|
|
* memory overrun. Note that a string
|
|
* value is counted as a single value regardless of length.
|
|
*
|
|
* @note The unpack function will return the actual number of values
|
|
* unpacked in this location.
|
|
*
|
|
* @param type The type of the data to be unpacked - must be one of
|
|
* the DSS defined data types.
|
|
*
|
|
* @retval *max_num_values The number of values actually unpacked. In
|
|
* most cases, this should match the maximum number provided in the
|
|
* parameters - but in no case will it exceed the value of this
|
|
* parameter. Note that if you unpack fewer values than are actually
|
|
* available, the buffer will be in an unpackable state - the dss will
|
|
* return an error code to warn of this condition.
|
|
*
|
|
* @retval OPAL_SUCCESS The next item in the buffer was successfully
|
|
* unpacked.
|
|
*
|
|
* @retval OPAL_ERROR(s) The unpack function returns an error code
|
|
* under one of several conditions: (a) the number of values in the
|
|
* item exceeds the max num provided by the caller; (b) the type of
|
|
* the next item in the buffer does not match the type specified by
|
|
* the caller; or (c) the unpack failed due to either an error in the
|
|
* buffer or an attempt to read past the end of the buffer.
|
|
*
|
|
* @code
|
|
* opal_buffer_t *buffer;
|
|
* int32_t dest;
|
|
* char **string_array;
|
|
* int32_t num_values;
|
|
*
|
|
* num_values = 1;
|
|
* status_code = opal_dss.unpack(buffer, (void*)&dest, &num_values, OPAL_INT32);
|
|
*
|
|
* num_values = 5;
|
|
* string_array = malloc(num_values*sizeof(char *));
|
|
* status_code = opal_dss.unpack(buffer, (void*)(string_array), &num_values, OPAL_STRING);
|
|
*
|
|
* @endcode
|
|
*/
|
|
typedef int (*opal_dss_unpack_fn_t)(opal_buffer_t *buffer, void *dest,
|
|
int32_t *max_num_values,
|
|
opal_data_type_t type);
|
|
|
|
/**
|
|
* Get the type and number of values of the next item in the buffer.
|
|
*
|
|
* The peek function looks at the next item in the buffer and returns
|
|
* both its type and the number of values in the item. This is a
|
|
* non-destructive function call that does not disturb the buffer, so
|
|
* it can be called multiple times if desired.
|
|
*
|
|
* @param buffer A pointer to the buffer in question.
|
|
*
|
|
* @param type A pointer to an opal_data_type_t variable where the
|
|
* type of the next item in the buffer is to be stored. Caller must
|
|
* have memory backing this location.
|
|
*
|
|
* @param number A pointer to a int32_t variable where the number of
|
|
* data values in the next item is to be stored. Caller must have
|
|
* memory backing this location.
|
|
*
|
|
* @retval OPAL_SUCCESS Requested info was successfully returned.
|
|
* @retval OPAL_ERROR(s) An appropriate error code indicating the
|
|
* problem will be returned. This should be handled appropriately by
|
|
* the caller.
|
|
*
|
|
*/
|
|
typedef int (*opal_dss_peek_next_item_fn_t)(opal_buffer_t *buffer,
|
|
opal_data_type_t *type,
|
|
int32_t *number);
|
|
|
|
/**
|
|
* Unload the data payload from a buffer.
|
|
*
|
|
* The unload function provides the caller with a pointer to the data
|
|
* payload within the buffer and the size of that payload. This allows
|
|
* the user to directly access the payload - typically used in the RML
|
|
* to unload the payload from the buffer for transmission.
|
|
*
|
|
* @note This is a destructive operation. While the payload is
|
|
* undisturbed, the function will clear the buffer's pointers to the
|
|
* payload. Thus, the buffer and the payload are completely separated,
|
|
* leaving the caller free to OBJ_RELEASE the buffer.
|
|
*
|
|
* @param buffer A pointer to the buffer whose payload is to be
|
|
* unloaded.
|
|
*
|
|
* @param payload The address to a void* pointer that is to be loaded
|
|
* with the address of the data payload in the buffer.
|
|
*
|
|
* @param size The size (in bytes) of the data payload in the buffer.
|
|
*
|
|
* @retval OPAL_SUCCESS The request was succesfully completed.
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate error code indicating the
|
|
* problem will be returned. This should be handled appropriately by
|
|
* the caller.
|
|
*
|
|
* @code
|
|
* opal_buffer_t *buffer;
|
|
* uint8_t *bytes;
|
|
* int32_t size;
|
|
*
|
|
* status_code = opal_dss.unload(buffer, (void**)(&bytes), &size);
|
|
* OBJ_RELEASE(buffer);
|
|
* @endcode
|
|
*/
|
|
typedef int (*opal_dss_unload_fn_t)(opal_buffer_t *buffer,
|
|
void **payload,
|
|
int32_t *size);
|
|
|
|
/**
|
|
* Load a data payload into a buffer.
|
|
*
|
|
* The load function allows the caller to replace the payload in a
|
|
* buffer with one provided by the caller. If a payload already exists
|
|
* in the buffer, the function will "free" the existing data to
|
|
* release it, and then replace the data payload with the one provided
|
|
* by the caller.
|
|
*
|
|
* @note The buffer must be allocated in advance via the OBJ_NEW
|
|
* function call - failing to do so will cause the load function to
|
|
* return an error code.
|
|
*
|
|
* @note The caller is responsible for pre-packing the provided
|
|
* payload - the load function cannot convert to network byte order
|
|
* any data contained in the provided payload.
|
|
*
|
|
* @param buffer A pointer to the buffer into which lthe payload is to
|
|
* be loaded.
|
|
*
|
|
* @param payload A void* pointer to the payload to be loaded into the
|
|
* buffer.
|
|
*
|
|
* @param size The size (in bytes) of the provided payload.
|
|
*
|
|
* @retval OPAL_SUCCESS The request was successfully completed
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate error code indicating the
|
|
* problem will be returned. This should be handled appropriately by
|
|
* the caller.
|
|
*
|
|
* @code
|
|
* opal_buffer_t *buffer;
|
|
* uint8_t bytes;
|
|
* int32_t size;
|
|
*
|
|
* buffer = OBJ_NEW(opal_buffer_t);
|
|
* status_code = opal_dss.load(buffer, (void*)(&bytes), size);
|
|
* @endcode
|
|
*/
|
|
typedef int (*opal_dss_load_fn_t)(opal_buffer_t *buffer,
|
|
void *payload,
|
|
int32_t size);
|
|
|
|
|
|
/**
|
|
* Copy a payload from one buffer to another
|
|
* This function will append a copy of the payload in one buffer into
|
|
* another buffer. If the destination buffer is NOT empty, then the
|
|
* type of the two buffers MUST match or else an
|
|
* error will be returned. If the destination buffer IS empty, then
|
|
* its type will be set to that of the source buffer.
|
|
* NOTE: This is NOT a destructive procedure - the
|
|
* source buffer's payload will remain intact, as will any pre-existing
|
|
* payload in the destination's buffer.
|
|
*/
|
|
typedef int (*opal_dss_copy_payload_fn_t)(opal_buffer_t *dest,
|
|
opal_buffer_t *src);
|
|
|
|
/**
|
|
* DSS register function
|
|
*
|
|
* This function registers variables associated with the DSS system.
|
|
*/
|
|
OPAL_DECLSPEC int opal_dss_register_vars (void);
|
|
|
|
/**
|
|
* DSS initialization function.
|
|
*
|
|
* In dynamic libraries, declared objects and functions don't get
|
|
* loaded until called. We need to ensure that the opal_dss function
|
|
* structure gets loaded, so we provide an "open" call that is
|
|
* executed as part of the program startup.
|
|
*/
|
|
OPAL_DECLSPEC int opal_dss_open(void);
|
|
|
|
/**
|
|
* DSS finalize function
|
|
*/
|
|
OPAL_DECLSPEC int opal_dss_close(void);
|
|
|
|
|
|
/**
|
|
* Copy a data value from one location to another.
|
|
*
|
|
* Since registered data types can be complex structures, the system
|
|
* needs some way to know how to copy the data from one location to
|
|
* another (e.g., for storage in the registry). This function, which
|
|
* can call other copy functions to build up complex data types, defines
|
|
* the method for making a copy of the specified data type.
|
|
*
|
|
* @param **dest The address of a pointer into which the
|
|
* address of the resulting data is to be stored.
|
|
*
|
|
* @param *src A pointer to the memory location from which the
|
|
* data is to be copied.
|
|
*
|
|
* @param type The type of the data to be copied - must be one of
|
|
* the DSS defined data types.
|
|
*
|
|
* @retval OPAL_SUCCESS The value was successfully copied.
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate error code.
|
|
*
|
|
*/
|
|
typedef int (*opal_dss_copy_fn_t)(void **dest, void *src, opal_data_type_t type);
|
|
|
|
/**
|
|
* Compare two data values.
|
|
*
|
|
* Since registered data types can be complex structures, the system
|
|
* needs some way to know how to compare two data values (e.g., when
|
|
* trying to order them in some fashion). This function, which
|
|
* can call other compare functions to build up complex data types, defines
|
|
* the method for comparing two values of the specified data type.
|
|
*
|
|
* @retval -1 Indicates first value is greater than second value
|
|
* @retval 0 Indicates two values are equal
|
|
* @retval +1 Indicates second value is greater than first value
|
|
*/
|
|
typedef int (*opal_dss_compare_fn_t)(const void *value1, const void *value2,
|
|
opal_data_type_t type);
|
|
|
|
|
|
/**
|
|
* Print a data value.
|
|
*
|
|
* Since registered data types can be complex structures, the system
|
|
* needs some way to know how to print them (i.e., convert them to a string
|
|
* representation).
|
|
*
|
|
* @retval OPAL_SUCCESS The value was successfully printed.
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate error code.
|
|
*/
|
|
typedef int (*opal_dss_print_fn_t)(char **output, char *prefix, void *src, opal_data_type_t type);
|
|
|
|
|
|
/**
|
|
* Print a data value to an output stream for debugging purposes
|
|
*
|
|
* Uses the dss.print command to obtain a string version of the data value
|
|
* and prints it to the designated output stream.
|
|
*
|
|
* @retval OPAL_SUCCESS The value was successfully printed.
|
|
*
|
|
* @retval OPAL_ERROR(s) An appropriate error code.
|
|
*/
|
|
typedef int (*opal_dss_dump_fn_t)(int output_stream, void *src, opal_data_type_t type);
|
|
|
|
/**
|
|
* Register a set of data handling functions.
|
|
*
|
|
* * This function registers a set of data type functions for a specific
|
|
* type. An integer is returned that should be used a an argument to
|
|
* future invocations of opal_dss.pack(), opal_dss.unpack(), opal_dss.copy(),
|
|
* and opal_dss.compare, which
|
|
* will trigger calls to the appropriate functions. This
|
|
* is most useful when extending the datatypes that the dss can
|
|
* handle; pack and unpack functions can nest calls to opal_dss.pack()
|
|
* / opal_dss.unpack(), so defining small pack/unpack functions can be
|
|
* used recursively to build larger types (e.g., packing/unpacking
|
|
* structs can use calls to opal_dss.pack()/unpack() to serialize /
|
|
* deserialize individual members). This is likewise true for the copy
|
|
* and compare functions.
|
|
*
|
|
* @param pack_fn [IN] Function pointer to the pack routine
|
|
* @param unpack_fn [IN] Function pointer to the unpack routine
|
|
* @param copy_fn [IN] Function pointer to copy routine
|
|
* @param compare_fn [IN] Function pointer to compare routine
|
|
* @param print_fn [IN] Function pointer to print routine
|
|
* @param structured [IN] Boolean indicator as to whether or not the data is structured. A true
|
|
* value indicates that this data type is always passed via reference (i.e., a pointer to the
|
|
* object is passed) as opposed to directly (e.g., the way an int32_t would appear)
|
|
* @param name [IN] String name for this pair (mainly for debugging)
|
|
* @param type [OUT] Type number for this registration
|
|
*
|
|
* @returns OPAL_SUCCESS upon success
|
|
*
|
|
*/
|
|
typedef int (*opal_dss_register_fn_t)(opal_dss_pack_fn_t pack_fn,
|
|
opal_dss_unpack_fn_t unpack_fn,
|
|
opal_dss_copy_fn_t copy_fn,
|
|
opal_dss_compare_fn_t compare_fn,
|
|
opal_dss_print_fn_t print_fn,
|
|
bool structured,
|
|
const char *name, opal_data_type_t *type);
|
|
/*
|
|
* This function looks up the string name corresponding to the identified
|
|
* data type - used for debugging messages.
|
|
*/
|
|
typedef char* (*opal_dss_lookup_data_type_fn_t)(opal_data_type_t type);
|
|
|
|
/*
|
|
* Dump the data type list - used for debugging to see what has been registered
|
|
*/
|
|
typedef void (*opal_dss_dump_data_types_fn_t)(int output);
|
|
|
|
/* return true if the data type is structured */
|
|
typedef bool (*opal_dss_structured_fn_t)(opal_data_type_t type);
|
|
|
|
/**
|
|
* Base structure for the DSS
|
|
*
|
|
* Base module structure for the DSS - presents the required function
|
|
* pointers to the calling interface.
|
|
*/
|
|
struct opal_dss_t {
|
|
opal_dss_pack_fn_t pack;
|
|
opal_dss_unpack_fn_t unpack;
|
|
opal_dss_copy_fn_t copy;
|
|
opal_dss_compare_fn_t compare;
|
|
opal_dss_print_fn_t print;
|
|
opal_dss_structured_fn_t structured;
|
|
opal_dss_peek_next_item_fn_t peek;
|
|
opal_dss_unload_fn_t unload;
|
|
opal_dss_load_fn_t load;
|
|
opal_dss_copy_payload_fn_t copy_payload;
|
|
opal_dss_register_fn_t register_type;
|
|
opal_dss_lookup_data_type_fn_t lookup_data_type;
|
|
opal_dss_dump_data_types_fn_t dump_data_types;
|
|
opal_dss_dump_fn_t dump;
|
|
};
|
|
typedef struct opal_dss_t opal_dss_t;
|
|
|
|
OPAL_DECLSPEC extern opal_dss_t opal_dss; /* holds dss function pointers */
|
|
|
|
END_C_DECLS
|
|
|
|
#endif /* OPAL_DSS_H */
|