/* * Copyright (c) 2004-2005 The Trustees of Indiana University. * All rights reserved. * Copyright (c) 2004-2005 The Trustees of the University of Tennessee. * 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$ * * Additional copyrights may follow * * $HEADER$ */ /** * @file * * Run-time MCA message buffer interface for packing/unpacking messages * these routines are used by both the OOB and the registry. */ #ifndef OMPI_MCA_BASE_MSGBUF_H #define OMPI_MCA_BASE_MSGBUF_H /**************************************************************************/ /* * packed message buffer interface, moved to mca_base so that all MCA modules can * access it */ /* exposed interface to the packed message buffer system */ typedef enum { MCA_BASE_MSGBUF_BYTE, MCA_BASE_MSGBUF_INT32, MCA_BASE_MSGBUF_INT64, MCA_BASE_MSGBUF_INT128, MCA_BASE_MSGBUF_REAL32, MCA_BASE_MSGBUF_REAL64, MCA_BASE_MSGBUF_PACKED, MCA_BASE_MSGBUF_BYTE_BY_REF } mca_base_msgbuf_data_t; /* * The data types are simple and are required for each pack/unpack * The user is expected to unpack the data in the same order as they packed. * The system may or maynot type the message. * * Special types * MCA_BASE_MSGBUF_BYTE does not get converted. * MCA_BASE_MSGBUF_PACKED packs a packed buffer into another buffer. * MCA_BASE_MSGBUF_PACKED should be unpacked into a new buffer (returned in 'ptr'). * MCA_BASE_MSGBUF_BYTE_BY_REF only has real meaning during packing. The system would * avoid copying this memory if possible. * The receiver would need to unpack by using either MCA_BASE_MSGBUF_BYTE/_BY_REF. * */ /* * the definition of the msgbuf is opaque completely */ typedef struct mca_base_msgbuffer_s* mca_base_msgbuf_t; /* * get/create a free buffer * * @param reqsize requested size for the buffer * * @retval mca_base_msgbuf_t handle to a message buffer * * if reqsize = MCA_BASE_MSGBUF_GETBUF, then the system gives an * unlimited buffer. * * Giving a req size just makes it more memory efficient. */ OMPI_DECLSPEC mca_base_msgbuf_t mca_base_msgbuf_new (size_t reqsize); /* make a copy of an existing buffer * * @param mca_base_msgbuf_t handle to an existing message buffer * @param return a new buffer handle via a pointer argument * * @retval sucess or failue int * * this is usefull for the registry and is needed as unpack is * destructive */ OMPI_DECLSPEC int mca_base_msgbuf_copy (mca_base_msgbuf_t* copybufid, mca_base_msgbuf_t orgbufid); /* set a buffer to a block of memory so that you do not pack/memory copy * * @param ptr Pointer to users memory to be send * @param datasize Length of the memory in bytes that needs to be sent * * @retval mca_base_msgbuf_t message buffer that points to this userdata * * As base_pack send/recv handles buffer you might not want * to pack a buffer but do a send from memory directly * a free on this special buffer just frees its structure not the memory */ OMPI_DECLSPEC mca_base_msgbuf_t mca_base_msgbuf_construct (void* ptr, size_t datasize); /* explicit free of a buffer when not auto freeing them * * @param mca_base_msgbuf_t buffer handle that you request to be freed * * @retval success or error code * * This routine resets the handle the user passing inso that they can only * free it once */ OMPI_DECLSPEC int mca_base_msgbuf_free (mca_base_msgbuf_t* bufid); /* pack and non-string typed data * * @param mca_base_msgbuf_t bufid buffer handle where data is packed * @param void* ptr Pointer to users memory to pack from * @param size_t num_items Number of items to pack into buffer bufid * @param mca_base_msgbuf_data_t datatype Type of item being packed * * @retval if zero or greater the items packed, if negative error code * * If the buffer fills up, it will automatically resize unless allocated * with fixed buffer size. */ OMPI_DECLSPEC int mca_base_msgbuf_pack (mca_base_msgbuf_t bufid, void* ptr, size_t num_items, mca_base_msgbuf_data_t datatype); /* unpack non-string typed data * * @param mca_base_msgbuf_t bufid buffer handle where data is packed * @param void* ptr Pointer to users memory to unpack into * @param size_t num_items Number of items to unpack from the buffer bufid * @param mca_base_msgbuf_data_t datatype Type of item being unpacked * * @retval if zero or greater the items unpacked, if negative error code * * Once the buffer empties, the buffer is freed. * If the remain data in the buffer is not large enought for the unpack * request, the routine will unpack what it can and then return an error. * The user is responsible for unpacking a message correctly. */ OMPI_DECLSPEC int mca_base_msgbuf_unpack (mca_base_msgbuf_t bufid, void* ptr, size_t num_items, mca_base_msgbuf_data_t datatype); /* pack a NULL terminated string * * @param mca_base_msgbuf_t bufid buffer handle where data is packed * @param strptr Pointer to NULL terminated string to pack * * @retval if zero or greater the items packed, if negative error code * * If the buffer fills up, it will automatically resize unless allocated * with a fixed buffer size. */ OMPI_DECLSPEC int mca_base_msgbuf_pack_string (mca_base_msgbuf_t bufid, char* strptr); /* unpack a NULL terminated string * * @param mca_base_msgbuf_t bufid buffer handle where data is already packed * @param char* strptr Pointer to memory to unpack string into * @param maxlen maximum size of the memory available to unpack into * * @retval if zero or greater the items (un)packed, if negative error code * * If the memory given is smaller than the string (strlen(str)) + 1 * then the routine truncates the string but always NULL terminates it. * */ OMPI_DECLSPEC int mca_base_msgbuf_unpack_string (mca_base_msgbuf_t bufid, char* strptr, size_t maxlen); /* constants */ #define MCA_BASE_MSGBUF_NULL_BUFID -1 /* default buffer ID returned when freeing */ #define MCA_BASE_MSGBUF_GETBUF -2000 /* default system give me a buffer const */ /* error codes */ #define MCA_BASE_MSGBUF_SUCCESS 0; /* buffer error codes */ #define MCA_BASE_MSGBUF_BADBUFFER -2010 /* bad buffer id */ #define MCA_BASE_MSGBUF_OUTOFBUFFERS -2011 /* no free msg buffers free */ #define MCA_BASE_MSGBUF_OUTOFMEMORY -2012 /* cannot allocate any more memory for message buffers */ #define MCA_BASE_MSGBUF_BADPARM -2014 /* other parameters are bad/invalid pointers */ #define MCA_BASE_MSGBUF_BADDATA -2015 /* to/from data addr is bad (null etc) */ #endif /* OMPI_MCA_BASE_MSGBUF_H */