00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2005 Nils van Velzen 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 */ 00019 #ifndef CTA_PACK_H 00020 #define CTA_PACK_H 00021 #include "cta_system.h" 00022 #include "cta_handles.h" 00023 #include "cta_datatypes.h" 00024 00025 /** 00026 \file cta_pack.h 00027 00028 \brief The interface description of the COSTA pack component. 00029 00030 The pack component is used for storing non-sequential data before it is 00031 saved to file communicated in a parallel environment. 00032 The pack component contains a memory buffer that can be filled with data. The size of the buffer is 00033 automatically increased when new data is added. 00034 00035 The pack component uses the FIFO princeple. Data that is added first can be retreved first. 00036 00037 */ 00038 00039 /* Function Handle */ 00040 typedef CTA_Handle CTA_Pack; 00041 00042 /*! Reset pack/unpack pointer of pack object */ 00043 #define CTA_PACK_RESET (-1) 00044 00045 #ifdef __cplusplus 00046 extern "C" { 00047 #endif 00048 00049 /** \brief Create a pack instance. 00050 * 00051 * \param initsize I the initial size >=0 of the buffer 00052 * \param hpack O receives handle of new pack object 00053 * 00054 * \return error status: CTA_OK if successful 00055 */ 00056 CTAEXPORT int CTA_Pack_Create(int initsize, CTA_Pack *hpack); 00057 00058 /** \brief Free a pack instance. 00059 * 00060 * \param hpack IO handle of pack object, replaced by CTA_NULL on return 00061 * 00062 * \return error status: CTA_OK if successful 00063 */ 00064 CTAEXPORT int CTA_Pack_Free(CTA_Pack *hpack); 00065 00066 /** \brief Add data to pack object. 00067 * 00068 * \param hpack IO handle of pack object 00069 * \param data I data that must be packed 00070 * \param lendat I size of the data to be packed (chars) 00071 * 00072 * \return error status: CTA_OK if successful 00073 */ 00074 CTAEXPORT int CTA_Pack_Add(CTA_Pack hpack, void *data, int lendat); 00075 00076 /** \brief Unpack (get) data from pack object. 00077 * 00078 * \param hpack IO handle of pack object 00079 * \param data O buffer that receives data that is unpacked from pack-buffer (buffer length must be >= lendat) 00080 * \param lendat I size of the data to be unpacked (chars) 00081 * 00082 * \return error status: CTA_OK if successful 00083 */ 00084 CTAEXPORT int CTA_Pack_Get(CTA_Pack hpack, void *data, int lendat); 00085 00086 /** \brief Get pointer to pack-buffer. 00087 * 00088 * \param hpack I handle of pack object 00089 * 00090 * \return pointer to buffer 00091 */ 00092 CTAEXPORT char* CTA_Pack_GetPtr(CTA_Pack hpack); 00093 00094 /** \brief Get length of packed data in pack-buffer. 00095 * 00096 * \param hpack I handle of pack object 00097 * 00098 * \return length packed data 00099 */ 00100 CTAEXPORT int CTA_Pack_GetLen(CTA_Pack hpack); 00101 00102 /** \brief Only update administration for added elements 00103 * 00104 * This function can be used to update the administration after the 00105 * pack-buffer is filled externally (e.g. using an mpi_recv) 00106 * 00107 * \param hpack I handle of pack object 00108 * \param lendat I number of added elements (chars) 00109 * 00110 * \return length packed data 00111 */ 00112 CTAEXPORT int CTA_Pack_AddCnt(CTA_Pack hpack, int lendat); 00113 00114 /** \brief Get the internal pack and unpack pointers 00115 * 00116 * This function can be used to save to pointers and 00117 * reset the state of the pack component after unpacking or adding 00118 * some data 00119 * 00120 * \param hpack I handle of pack object 00121 * \param ip1 O unpack pointer 00122 * \param ip2 O pack pointer 00123 * 00124 * \return length packed data 00125 */ 00126 CTAEXPORT int CTA_Pack_GetIndx(CTA_Pack hpack, int *ip1, int *ip2); 00127 00128 /** \brief Set the internal pack and unpack pointers 00129 * 00130 * This function can be used to restore the pointers and 00131 * reset the state of the pack component after unpacking or adding 00132 * some data 00133 * 00134 * \param hpack I handle of pack object 00135 * \param ip1 I unpack pointer. In order to reset all unpackin 00136 * set to CTA_PACK_RESET 00137 * \param ip2 I pack pointer. In order to reset the whole pack object 00138 * set to CTA_PACK_RESET 00139 * 00140 * \return length packed data 00141 */ 00142 00143 00144 CTAEXPORT int CTA_Pack_SetIndx(CTA_Pack hpack, int ip1, int ip2); 00145 00146 #ifdef __cplusplus 00147 } 00148 #endif 00149 #endif