From c43f785ab0ef880e4a5043dad184274f50ccb9c4 Mon Sep 17 00:00:00 2001 From: Achim Gsell Date: Thu, 17 May 2007 16:30:37 +0000 Subject: [PATCH] src/H5Block.c - more doxygen doc added --- src/H5Block.c | 242 +++++++++++++++++++++++++++++++------------------- 1 file changed, 152 insertions(+), 90 deletions(-) diff --git a/src/H5Block.c b/src/H5Block.c index 7d673d3..ddd4b96 100644 --- a/src/H5Block.c +++ b/src/H5Block.c @@ -125,11 +125,13 @@ _init ( } b = f->block; memset ( b, 0, sizeof (*b) ); - b->user_layout = (struct H5BlockPartition*) malloc ( f->nprocs * sizeof (b->user_layout[0]) ); + b->user_layout = (struct H5BlockPartition*) malloc ( + f->nprocs * sizeof (b->user_layout[0]) ); if ( b->user_layout == NULL ) { return HANDLE_H5PART_NOMEM_ERR; } - b->write_layout = (struct H5BlockPartition*) malloc ( f->nprocs * sizeof (b->write_layout[0]) ); + b->write_layout = (struct H5BlockPartition*) malloc ( + f->nprocs * sizeof (b->write_layout[0]) ); if ( b->write_layout == NULL ) { return HANDLE_H5PART_NOMEM_ERR; } @@ -158,7 +160,7 @@ _init ( */ static h5part_int64_t _close ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { herr_t herr; @@ -216,7 +218,7 @@ _close ( */ static void _normalize_partition ( - struct H5BlockPartition *p + struct H5BlockPartition *p /*!< IN/OUT: partition */ ) { h5part_float64_t x; @@ -249,7 +251,7 @@ _normalize_partition ( #ifdef PARALLEL_IO static h5part_int64_t _allgather ( - const H5PartFile *f + const H5PartFile *f /*!< IN: file handle */ ) { struct H5BlockPartition *partition = &f->block->user_layout[f->myproc]; struct H5BlockPartition *layout = f->block->user_layout; @@ -268,7 +270,7 @@ _allgather ( #else static h5part_int64_t _allgather ( - const H5PartFile *f + const H5PartFile *f /*!< IN: file handle */ ) { return H5PART_SUCCESS; @@ -285,7 +287,7 @@ _allgather ( */ static void _get_dimension_sizes ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { int proc; struct H5BlockStruct *b = f->block; @@ -306,28 +308,20 @@ _get_dimension_sizes ( || (p->j_end < q->j_start) \ || (p->k_end < q->k_start) ) -/* -#define _HAVE_GHOSTZONE(p,q) ( (p->i_end >= q->i_start) \ - && (p->j_end >= q->j_start) \ - && (p->k_end >= q->k_start) \ - && (q->i_end >= p->i_start) \ - && (q->j_end >= p->j_start) \ - && (q->k_end >= p->k_start) ) -*/ /*! \ingroup h5block_private \internal - Check whether to partition have a common ghost-zone. + Check whether two partitions have a common ghost-zone. \return value != \c 0 if yes otherwise \c 0 */ static int _have_ghostzone ( - const struct H5BlockPartition *p, - const struct H5BlockPartition *q + const struct H5BlockPartition *p, /*!< IN: partition \c p */ + const struct H5BlockPartition *q /*!< IN: partition \c q */ ) { return ( ! ( _NO_GHOSTZONE ( p, q ) || _NO_GHOSTZONE ( q, p ) ) ); } @@ -343,7 +337,7 @@ _have_ghostzone ( */ static h5part_int64_t _volume_of_partition ( - const struct H5BlockPartition *p + const struct H5BlockPartition *p /*!< IN: partition */ ) { return (p->i_end - p->i_start) * (p->j_end - p->j_start) @@ -365,8 +359,8 @@ _volume_of_partition ( */ static h5part_int64_t _volume_of_ghostzone ( - const struct H5BlockPartition *p, /*!< pointer to first partition */ - const struct H5BlockPartition *q /*!< pointer to second partition */ + const struct H5BlockPartition *p, /*!< IN: ptr to first partition */ + const struct H5BlockPartition *q /*!< IN: ptr to second partition */ ) { h5part_int64_t dx = MIN ( p->i_end, q->i_end ) @@ -392,8 +386,8 @@ _volume_of_ghostzone ( */ static h5part_int64_t _dissolve_X_ghostzone ( - struct H5BlockPartition *p, /*!< pointer to first partition */ - struct H5BlockPartition *q /*!< pointer to second partition */ + struct H5BlockPartition *p, /*!< IN/OUT: ptr to first partition */ + struct H5BlockPartition *q /*!< IN/OUT: ptr to second partition */ ) { if ( p->i_start > q->i_start ) @@ -420,8 +414,8 @@ _dissolve_X_ghostzone ( */ static h5part_int64_t _dissolve_Y_ghostzone ( - struct H5BlockPartition *p, /*!< pointer to first partition */ - struct H5BlockPartition *q /*!< pointer to second partition */ + struct H5BlockPartition *p, /*!< IN/OUT: ptr to first partition */ + struct H5BlockPartition *q /*!< IN/OUT: ptr to second partition */ ) { if ( p->j_start > q->j_start ) @@ -448,8 +442,8 @@ _dissolve_Y_ghostzone ( */ static h5part_int64_t _dissolve_Z_ghostzone ( - struct H5BlockPartition *p,/*!< pointer to first partition */ - struct H5BlockPartition *q /*!< pointer to second partition */ + struct H5BlockPartition *p, /*!< IN/OUT: ptr to first partition */ + struct H5BlockPartition *q /*!< IN/OUT: ptr to second partition */ ) { if ( p->k_start > q->k_start ) @@ -479,8 +473,8 @@ _dissolve_Z_ghostzone ( */ static h5part_int64_t _dissolve_ghostzone ( - struct H5BlockPartition *p,/*!< pointer to first partition */ - struct H5BlockPartition *q /*!< pointer to second partition */ + struct H5BlockPartition *p, /*!< IN/OUT: ptr to first partition */ + struct H5BlockPartition *q /*!< IN/OUT: ptr to second partition */ ) { struct H5BlockPartition p_; @@ -558,7 +552,7 @@ _dissolve_ghostzone ( */ static h5part_int64_t _dissolve_ghostzones ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { struct H5BlockStruct *b = f->block; @@ -670,7 +664,7 @@ _dissolve_ghostzones ( */ h5part_int64_t _release_hyperslab ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { herr_t herr; @@ -826,6 +820,8 @@ H5Block3dGetReducedPartitionOfProc ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dGetProcOf ( @@ -859,10 +855,11 @@ H5Block3dGetProcOf ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _open_block_group ( - const H5PartFile *f + const H5PartFile *f /*!< IN: file handle */ ) { h5part_int64_t herr; @@ -905,10 +902,11 @@ _have_object ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _open_field_group ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name ) { @@ -934,10 +932,11 @@ _open_field_group ( \internal + \return \c H5PART_SUCCESS or error code */ h5part_int64_t _close_field_group ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { herr_t herr = H5Gclose ( f->block->field_group_id ); @@ -951,10 +950,11 @@ _close_field_group ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _select_hyperslab_for_reading ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ hid_t dataset ) { @@ -1038,10 +1038,11 @@ _select_hyperslab_for_reading ( \internal + \return \c H5PART_SUCCESS or error code */ h5part_int64_t _read_data ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, h5part_float64_t *data ) { @@ -1071,10 +1072,12 @@ _read_data ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dReadScalarField ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, h5part_float64_t *data ) { @@ -1098,10 +1101,12 @@ H5Block3dReadScalarField ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dRead3dVectorField ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, h5part_float64_t *x_data, h5part_float64_t *y_data, @@ -1136,10 +1141,11 @@ H5Block3dRead3dVectorField ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _select_hyperslab_for_writing ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { /* @@ -1251,10 +1257,11 @@ _select_hyperslab_for_writing ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _create_block_group ( - const H5PartFile *f + const H5PartFile *f /*!< IN: file handle */ ) { herr_t herr; @@ -1278,10 +1285,11 @@ _create_block_group ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _create_field_group ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name ) { @@ -1314,10 +1322,11 @@ _create_field_group ( \internal + \return \c H5PART_SUCCESS or error code */ h5part_int64_t _write_data ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, const h5part_float64_t *data ) { @@ -1351,10 +1360,12 @@ _write_data ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dWriteScalarField ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, const h5part_float64_t *data ) { @@ -1387,7 +1398,7 @@ H5Block3dWriteScalarField ( */ h5part_int64_t H5Block3dWrite3dVectorField ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *name, const h5part_float64_t *x_data, const h5part_float64_t *y_data, @@ -1420,10 +1431,14 @@ H5Block3dWrite3dVectorField ( /*! \ingroup h5block_c_api + + Query number of fields in current time step. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockGetNumFields ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { SET_FNAME ( "H5BlockGetNumFields" ); @@ -1441,10 +1456,11 @@ H5BlockGetNumFields ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _get_field_info ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *field_name, h5part_int64_t *grid_rank, h5part_int64_t *grid_dims, @@ -1492,10 +1508,12 @@ _get_field_info ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockGetFieldInfo ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const h5part_int64_t idx, char *field_name, const h5part_int64_t len_field_name, @@ -1523,10 +1541,12 @@ H5BlockGetFieldInfo ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockGetFieldInfoByName ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *field_name, h5part_int64_t *grid_rank, h5part_int64_t *grid_dims, @@ -1548,10 +1568,11 @@ H5BlockGetFieldInfoByName ( \internal + \return \c H5PART_SUCCESS or error code */ static h5part_int64_t _write_field_attrib ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *field_name, const char *attrib_name, const hid_t attrib_type, @@ -1578,10 +1599,12 @@ _write_field_attrib ( /*! \ingroup h5block_c_api + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockWriteFieldAttrib ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *field_name, const char *attrib_name, const h5part_int64_t attrib_type, @@ -1603,10 +1626,15 @@ H5BlockWriteFieldAttrib ( /*! \ingroup h5block_c_api + + Write string \c attrib_value as attribute \c attrib_name to field + \c field_name.. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockWriteFieldAttribString ( - H5PartFile *f, + H5PartFile *f, /*!< IN: file handle */ const char *field_name, const char *attrib_name, const char *attrib_value @@ -1626,11 +1654,15 @@ H5BlockWriteFieldAttribString ( /*! \ingroup h5block_c_api + + Query the number of attributes of field \c field_name. + + \return number of attributes or error code */ h5part_int64_t H5BlockGetNumFieldAttribs ( - H5PartFile *f, - const char *field_name + H5PartFile *f, /*!< IN: file handle */ + const char *field_name /*block; @@ -1720,13 +1761,17 @@ _read_field_attrib ( /*! \ingroup h5block_c_api + + Read attribute \c attrib_name of field \c field_name. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5BlockReadFieldAttrib ( - H5PartFile *f, - const char *field_name, - const char *attrib_name, - void *attrib_value + H5PartFile *f, /*!< IN: file handle */ + const char *field_name, /*!< IN: field name */ + const char *attrib_name, /*!< IN: attribute name */ + void *attrib_value /*!< OUT: value */ ) { SET_FNAME ( "H5PartReadFieldAttrib" ); @@ -1739,14 +1784,18 @@ H5BlockReadFieldAttrib ( /*! \ingroup h5block_c_api + + Get field origin. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dGetFieldOrigin ( - H5PartFile *f, - const char *field_name, - h5part_float64_t *x_origin, - h5part_float64_t *y_origin, - h5part_float64_t *z_origin + H5PartFile *f, /*!< IN: file handle */ + const char *field_name, /*!< IN: field name */ + h5part_float64_t *x_origin, /*!< OUT: X origin */ + h5part_float64_t *y_origin, /*!< OUT: Y origin */ + h5part_float64_t *z_origin /*!< OUT: Z origin */ ) { SET_FNAME ( "H5BlockSetFieldOrigin" ); @@ -1766,14 +1815,18 @@ H5Block3dGetFieldOrigin ( /*! \ingroup h5block_c_api + + Set field origin. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dSetFieldOrigin ( - H5PartFile *f, - const char *field_name, - const h5part_float64_t x_origin, - const h5part_float64_t y_origin, - const h5part_float64_t z_origin + H5PartFile *f, /*!< IN: file handle */ + const char *field_name, /*!< IN: field name */ + const h5part_float64_t x_origin, /*!< IN: X origin */ + const h5part_float64_t y_origin, /*!< IN: Y origin */ + const h5part_float64_t z_origin /*!< IN: Z origin */ ) { SET_FNAME ( "H5BlockSetFieldOrigin" ); @@ -1793,14 +1846,18 @@ H5Block3dSetFieldOrigin ( /*! \ingroup h5block_c_api + + Get field spacing. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dGetFieldSpacing ( - H5PartFile *f, - const char *field_name, - h5part_float64_t *x_spacing, - h5part_float64_t *y_spacing, - h5part_float64_t *z_spacing + H5PartFile *f, /*!< IN: file handle */ + const char *field_name, /*!< IN: field name */ + h5part_float64_t *x_spacing, /*!< OUT: X spacing */ + h5part_float64_t *y_spacing, /*!< OUT: Y spacing */ + h5part_float64_t *z_spacing /*!< OUT: Z spacing */ ) { SET_FNAME ( "H5BlockGetFieldSpacing" ); @@ -1820,14 +1877,18 @@ H5Block3dGetFieldSpacing ( /*! \ingroup h5block_c_api + + Set field spacing. + + \return \c H5PART_SUCCESS or error code */ h5part_int64_t H5Block3dSetFieldSpacing ( - H5PartFile *f, - const char *field_name, - const h5part_float64_t x_spacing, - const h5part_float64_t y_spacing, - const h5part_float64_t z_spacing + H5PartFile *f, /*!< IN: file handle */ + const char *field_name, /*!< IN: field name */ + const h5part_float64_t x_spacing, /*!< IN: X spacing */ + const h5part_float64_t y_spacing, /*!< IN: Y spacing */ + const h5part_float64_t z_spacing /*!< IN: Z spacing */ ) { SET_FNAME ( "H5BlockSetFieldSpacing" ); @@ -1851,11 +1912,12 @@ H5Block3dSetFieldSpacing ( /* Checks whether the current time-step has field data or not. - Returns 0 if field data is available otherwise H5PART_ERR_NOENTRY. + \return \c H5PART_SUCCESS if field data is available otherwise \c + H5PART_ERR_NOENTRY. */ h5part_int64_t H5BlockHasFieldData ( - H5PartFile *f + H5PartFile *f /*!< IN: file handle */ ) { SET_FNAME ( "H5BlockHasFieldData" );