H5Oshared.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * Programmer:  Quincey Koziol <koziol@hdfgroup.org>
00018  *              Friday, January 19, 2007
00019  *
00020  * Purpose:     This file contains inline definitions for "generic" routines
00021  *              supporting a "shared message interface" (ala Java) for object
00022  *              header messages that can be shared.  This interface is
00023  *              dependent on a bunch of macros being defined which define
00024  *              the name of the interface and "real" methods which need to
00025  *              be implemented for each message class that supports the
00026  *              shared message interface.
00027  */
00028 
00029 #ifndef H5Oshared_H
00030 #define H5Oshared_H
00031 
00032 
00033 /*-------------------------------------------------------------------------
00034  * Function:    H5O_SHARED_DECODE
00035  *
00036  * Purpose:     Decode an object header message that may be shared.
00037  *
00038  * Note:        The actual name of this routine can be different in each source
00039  *              file that this header file is included in, and must be defined
00040  *              prior to including this header file.
00041  *
00042  * Return:      Success:        Pointer to the new message in native form
00043  *              Failure:        NULL
00044  *
00045  * Programmer:  Quincey Koziol
00046  *              Friday, January 19, 2007
00047  *
00048  *-------------------------------------------------------------------------
00049  */
00050 static H5_inline void *
00051 H5O_SHARED_DECODE(H5F_t *f, hid_t dxpl_id, H5O_t *open_oh, unsigned mesg_flags,
00052     unsigned *ioflags, const uint8_t *p)
00053 {
00054     void *ret_value;            /* Return value */
00055 
00056     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_DECODE)
00057 
00058 #ifndef H5O_SHARED_TYPE
00059 #error "Need to define H5O_SHARED_TYPE macro!"
00060 #endif /* H5O_SHARED_TYPE */
00061 #ifndef H5O_SHARED_DECODE
00062 #error "Need to define H5O_SHARED_DECODE macro!"
00063 #endif /* H5O_SHARED_DECODE */
00064 #ifndef H5O_SHARED_DECODE_REAL
00065 #error "Need to define H5O_SHARED_DECODE_REAL macro!"
00066 #endif /* H5O_SHARED_DECODE_REAL */
00067 
00068     /* Check for shared message */
00069     if(mesg_flags & H5O_MSG_FLAG_SHARED) {
00070         /* Retrieve native message info indirectly through shared message */
00071         if(NULL == (ret_value = H5O_shared_decode(f, dxpl_id, open_oh, ioflags, p, H5O_SHARED_TYPE)))
00072             HGOTO_ERROR(H5E_OHDR, H5E_CANTDECODE, NULL, "unable to decode shared message")
00073 
00074         /* We currently do not support automatically fixing shared messages */
00075 #ifdef H5_STRICT_FORMAT_CHECKS
00076         if(*ioflags & H5O_DECODEIO_DIRTY)
00077             HGOTO_ERROR(H5E_OHDR, H5E_UNSUPPORTED, NULL, "unable to mark shared message dirty")
00078 #else /* H5_STRICT_FORMAT_CHECKS */
00079         *ioflags &= ~H5O_DECODEIO_DIRTY;
00080 #endif /* H5_STRICT_FORMAT_CHECKS */
00081     } /* end if */
00082     else {
00083         /* Decode native message directly */
00084         if(NULL == (ret_value = H5O_SHARED_DECODE_REAL(f, dxpl_id, open_oh, mesg_flags, ioflags, p)))
00085             HGOTO_ERROR(H5E_OHDR, H5E_CANTDECODE, NULL, "unable to decode native message")
00086     } /* end else */
00087 
00088 done:
00089     FUNC_LEAVE_NOAPI(ret_value)
00090 } /* end H5O_SHARED_DECODE() */
00091 
00092 
00093 /*-------------------------------------------------------------------------
00094  * Function:    H5O_SHARED_ENCODE
00095  *
00096  * Purpose:     Encode an object header message that may be shared.
00097  *
00098  * Note:        The actual name of this routine can be different in each source
00099  *              file that this header file is included in, and must be defined
00100  *              prior to including this header file.
00101  *
00102  * Return:      Success:        Non-negative
00103  *              Failure:        Negative
00104  *
00105  * Programmer:  Quincey Koziol
00106  *              Friday, January 19, 2007
00107  *
00108  *-------------------------------------------------------------------------
00109  */
00110 static H5_inline herr_t
00111 H5O_SHARED_ENCODE(H5F_t *f, hbool_t disable_shared, uint8_t *p, const void *_mesg)
00112 {
00113     const H5O_shared_t *sh_mesg = (const H5O_shared_t *)_mesg;     /* Pointer to shared message portion of actual message */
00114     herr_t ret_value = SUCCEED;         /* Return value */
00115 
00116     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_ENCODE)
00117 
00118 #ifndef H5O_SHARED_TYPE
00119 #error "Need to define H5O_SHARED_TYPE macro!"
00120 #endif /* H5O_SHARED_TYPE */
00121 #ifndef H5O_SHARED_ENCODE
00122 #error "Need to define H5O_SHARED_ENCODE macro!"
00123 #endif /* H5O_SHARED_ENCODE */
00124 #ifndef H5O_SHARED_ENCODE_REAL
00125 #error "Need to define H5O_SHARED_ENCODE_REAL macro!"
00126 #endif /* H5O_SHARED_ENCODE_REAL */
00127 
00128     /* Sanity check */
00129     HDassert(sh_mesg->type == H5O_SHARE_TYPE_UNSHARED || sh_mesg->msg_type_id == H5O_SHARED_TYPE->id);
00130 
00131     /* Check for message stored elsewhere */
00132     if(H5O_IS_STORED_SHARED(sh_mesg->type) && !disable_shared) {
00133         /* Encode shared message into buffer */
00134         if(H5O_shared_encode(f, p, sh_mesg) < 0)
00135             HGOTO_ERROR(H5E_OHDR, H5E_CANTENCODE, FAIL, "unable to encode shared message")
00136     } /* end if */
00137     else {
00138         /* Encode native message directly */
00139         if(H5O_SHARED_ENCODE_REAL(f, p, _mesg) < 0)
00140             HGOTO_ERROR(H5E_OHDR, H5E_CANTENCODE, FAIL, "unable to encode native message")
00141     } /* end else */
00142 
00143 done:
00144     FUNC_LEAVE_NOAPI(ret_value)
00145 } /* end H5O_SHARED_ENCODE() */
00146 
00147 
00148 /*-------------------------------------------------------------------------
00149  * Function:    H5O_SHARED_SIZE
00150  *
00151  * Purpose:     Returns the length of an encoded message.
00152  *
00153  * Note:        The actual name of this routine can be different in each source
00154  *              file that this header file is included in, and must be defined
00155  *              prior to including this header file.
00156  *
00157  * Return:      Success:        Length
00158  *              Failure:        0
00159  *
00160  * Programmer:  Quincey Koziol
00161  *              Friday, January 19, 2007
00162  *
00163  *-------------------------------------------------------------------------
00164  */
00165 static H5_inline size_t
00166 H5O_SHARED_SIZE(const H5F_t *f, hbool_t disable_shared, const void *_mesg)
00167 {
00168     const H5O_shared_t *sh_mesg = (const H5O_shared_t *)_mesg;     /* Pointer to shared message portion of actual message */
00169     size_t ret_value;           /* Return value */
00170 
00171     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_SIZE)
00172 
00173 #ifndef H5O_SHARED_TYPE
00174 #error "Need to define H5O_SHARED_TYPE macro!"
00175 #endif /* H5O_SHARED_TYPE */
00176 #ifndef H5O_SHARED_SIZE
00177 #error "Need to define H5O_SHARED_SIZE macro!"
00178 #endif /* H5O_SHARED_SIZE */
00179 #ifndef H5O_SHARED_SIZE_REAL
00180 #error "Need to define H5O_SHARED_SIZE_REAL macro!"
00181 #endif /* H5O_SHARED_SIZE_REAL */
00182 
00183     /* Check for message stored elsewhere */
00184     if(H5O_IS_STORED_SHARED(sh_mesg->type) && !disable_shared) {
00185         /* Retrieve encoded size of shared message */
00186         if(0 == (ret_value = H5O_shared_size(f, sh_mesg)))
00187             HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, 0, "unable to retrieve encoded size of shared message")
00188     } /* end if */
00189     else {
00190         /* Retrieve size of native message directly */
00191         if(0 == (ret_value = H5O_SHARED_SIZE_REAL(f, _mesg)))
00192             HGOTO_ERROR(H5E_OHDR, H5E_CANTGET, 0, "unable to retrieve encoded size of native message")
00193     } /* end else */
00194 
00195 done:
00196     FUNC_LEAVE_NOAPI(ret_value)
00197 } /* end H5O_SHARED_SIZE() */
00198 
00199 
00200 /*-------------------------------------------------------------------------
00201  * Function:    H5O_SHARED_DELETE
00202  *
00203  * Purpose:     Decrement reference count on any objects referenced by
00204  *              message
00205  *
00206  * Note:        The actual name of this routine can be different in each source
00207  *              file that this header file is included in, and must be defined
00208  *              prior to including this header file.
00209  *
00210  * Return:      Success:        Non-negative
00211  *              Failure:        Negative
00212  *
00213  * Programmer:  Quincey Koziol
00214  *              Friday, January 19, 2007
00215  *
00216  *-------------------------------------------------------------------------
00217  */
00218 static H5_inline herr_t
00219 H5O_SHARED_DELETE(H5F_t *f, hid_t dxpl_id, H5O_t *open_oh, void *_mesg)
00220 {
00221     H5O_shared_t *sh_mesg = (H5O_shared_t *)_mesg;     /* Pointer to shared message portion of actual message */
00222     herr_t ret_value = SUCCEED;         /* Return value */
00223 
00224     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_DELETE)
00225 
00226 #ifndef H5O_SHARED_TYPE
00227 #error "Need to define H5O_SHARED_TYPE macro!"
00228 #endif /* H5O_SHARED_TYPE */
00229 #ifndef H5O_SHARED_DELETE
00230 #error "Need to define H5O_SHARED_DELETE macro!"
00231 #endif /* H5O_SHARED_DELETE */
00232 
00233     /* Check for message tracked elsewhere */
00234     if(H5O_IS_TRACKED_SHARED(sh_mesg->type)) {
00235         /* Decrement the reference count on the shared message/object */
00236         if(H5O_shared_delete(f, dxpl_id, open_oh, H5O_SHARED_TYPE, sh_mesg) < 0)
00237             HGOTO_ERROR(H5E_OHDR, H5E_CANTDEC, FAIL, "unable to decrement ref count for shared message")
00238     } /* end if */
00239 #ifdef H5O_SHARED_DELETE_REAL
00240     else {
00241         /* Decrement the reference count on the native message directly */
00242         if(H5O_SHARED_DELETE_REAL(f, dxpl_id, open_oh, _mesg) < 0)
00243             HGOTO_ERROR(H5E_OHDR, H5E_CANTDEC, FAIL, "unable to decrement ref count for native message")
00244     } /* end else */
00245 #endif /* H5O_SHARED_DELETE_REAL */
00246 
00247 done:
00248     FUNC_LEAVE_NOAPI(ret_value)
00249 } /* end H5O_SHARED_DELETE() */
00250 
00251 
00252 /*-------------------------------------------------------------------------
00253  * Function:    H5O_SHARED_LINK
00254  *
00255  * Purpose:     Increment reference count on any objects referenced by
00256  *              message
00257  *
00258  * Note:        The actual name of this routine can be different in each source
00259  *              file that this header file is included in, and must be defined
00260  *              prior to including this header file.
00261  *
00262  * Return:      Success:        Non-negative
00263  *              Failure:        Negative
00264  *
00265  * Programmer:  Quincey Koziol
00266  *              Friday, January 19, 2007
00267  *
00268  *-------------------------------------------------------------------------
00269  */
00270 static H5_inline herr_t
00271 H5O_SHARED_LINK(H5F_t *f, hid_t dxpl_id, H5O_t *open_oh, void *_mesg)
00272 {
00273     H5O_shared_t *sh_mesg = (H5O_shared_t *)_mesg;     /* Pointer to shared message portion of actual message */
00274     herr_t ret_value = SUCCEED;         /* Return value */
00275 
00276     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_LINK)
00277 
00278 #ifndef H5O_SHARED_TYPE
00279 #error "Need to define H5O_SHARED_TYPE macro!"
00280 #endif /* H5O_SHARED_TYPE */
00281 #ifndef H5O_SHARED_LINK
00282 #error "Need to define H5O_SHARED_LINK macro!"
00283 #endif /* H5O_SHARED_LINK */
00284 
00285     /* Check for message tracked elsewhere */
00286     if(H5O_IS_TRACKED_SHARED(sh_mesg->type)) {
00287         /* Increment the reference count on the shared message/object */
00288         if(H5O_shared_link(f, dxpl_id, open_oh, H5O_SHARED_TYPE, sh_mesg) < 0)
00289             HGOTO_ERROR(H5E_OHDR, H5E_CANTINC, FAIL, "unable to increment ref count for shared message")
00290     } /* end if */
00291 #ifdef H5O_SHARED_LINK_REAL
00292     else {
00293         /* Increment the reference count on the native message directly */
00294         if(H5O_SHARED_LINK_REAL(f, dxpl_id, open_oh, _mesg) < 0)
00295             HGOTO_ERROR(H5E_OHDR, H5E_CANTINC, FAIL, "unable to increment ref count for native message")
00296     } /* end else */
00297 #endif /* H5O_SHARED_LINK_REAL */
00298 
00299 done:
00300     FUNC_LEAVE_NOAPI(ret_value)
00301 } /* end H5O_SHARED_LINK() */
00302 
00303 
00304 /*-------------------------------------------------------------------------
00305  * Function:    H5O_SHARED_COPY_FILE
00306  *
00307  * Purpose:     Copies a message from _SRC to _DEST in file
00308  *
00309  * Note:        The actual name of this routine can be different in each source
00310  *              file that this header file is included in, and must be defined
00311  *              prior to including this header file.
00312  *
00313  * Return:      Success:        Non-negative
00314  *              Failure:        Negative
00315  *
00316  * Programmer:  Quincey Koziol
00317  *              Friday, January 19, 2007
00318  *
00319  *-------------------------------------------------------------------------
00320  */
00321 static H5_inline void *
00322 H5O_SHARED_COPY_FILE(H5F_t *file_src, void *_native_src, H5F_t *file_dst,
00323     hbool_t *recompute_size, H5O_copy_t *cpy_info, void *udata, hid_t dxpl_id)
00324 {
00325     void *dst_mesg = NULL;      /* Destination message */
00326     void *ret_value;            /* Return value */
00327 
00328     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_COPY_FILE)
00329 
00330 #ifndef H5O_SHARED_TYPE
00331 #error "Need to define H5O_SHARED_TYPE macro!"
00332 #endif /* H5O_SHARED_TYPE */
00333 #ifndef H5O_SHARED_COPY_FILE
00334 #error "Need to define H5O_SHARED_COPY_FILE macro!"
00335 #endif /* H5O_SHARED_COPY_FILE */
00336 
00337 #ifdef H5O_SHARED_COPY_FILE_REAL
00338     /* Call native message's copy file callback to copy the message */
00339     if(NULL == (dst_mesg = H5O_SHARED_COPY_FILE_REAL(file_src, H5O_SHARED_TYPE, _native_src, file_dst, recompute_size, cpy_info, udata, dxpl_id)))
00340         HGOTO_ERROR(H5E_OHDR, H5E_CANTCOPY, NULL, "unable to copy native message to another file")
00341 #else /* H5O_SHARED_COPY_FILE_REAL */
00342     /* No copy file callback defined, just copy the message itself */
00343     if(NULL == (dst_mesg = (H5O_SHARED_TYPE->copy)(_native_src, NULL)))
00344         HGOTO_ERROR(H5E_OHDR, H5E_CANTCOPY, NULL, "unable to copy native message")
00345 #endif /* H5O_SHARED_COPY_FILE_REAL */
00346 
00347     /* Reset shared message info for new message */
00348     HDmemset(dst_mesg, 0, sizeof(H5O_shared_t));
00349 
00350     /* Handle sharing destination message */
00351     if(H5O_shared_copy_file(file_src, file_dst, H5O_SHARED_TYPE,
00352             _native_src, dst_mesg, recompute_size, cpy_info, udata, dxpl_id) < 0)
00353         HGOTO_ERROR(H5E_OHDR, H5E_WRITEERROR, NULL, "unable to determine if message should be shared")
00354 
00355     /* Set return value */
00356     ret_value = dst_mesg;
00357 
00358 done:
00359     if(!ret_value)
00360         if(dst_mesg)
00361             H5O_msg_free(H5O_SHARED_TYPE->id, dst_mesg);
00362 
00363     FUNC_LEAVE_NOAPI(ret_value)
00364 } /* end H5O_SHARED_COPY_FILE() */
00365 
00366 
00367 /*-------------------------------------------------------------------------
00368  * Function:    H5O_SHARED_POST_COPY_FILE
00369  *
00370  * Purpose:     Copies a message from _SRC to _DEST in file
00371  *
00372  * Note:        The actual name of this routine can be different in each source
00373  *              file that this header file is included in, and must be defined
00374  *              prior to including this header file.
00375  *
00376  * Return:      Success:        Non-negative
00377  *              Failure:        Negative
00378  *
00379  * Programmer:  Peter Cao
00380  *              May 25, 2007
00381  *
00382  *-------------------------------------------------------------------------
00383  */
00384 static H5_inline herr_t
00385 H5O_SHARED_POST_COPY_FILE(const H5O_loc_t *oloc_src, const void *mesg_src,
00386     H5O_loc_t *oloc_dst, void *mesg_dst, hid_t dxpl_id, H5O_copy_t *cpy_info)
00387 {
00388     const H5O_shared_t  *shared_dst = (const H5O_shared_t *)mesg_dst; /* Alias to shared info in native source */
00389     herr_t ret_value = SUCCEED;         /* Return value */
00390 
00391     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_POST_COPY_FILE)
00392 
00393     HDassert(oloc_src->file);
00394     HDassert(oloc_dst->file);
00395     HDassert(mesg_src);
00396     HDassert(mesg_dst);
00397 
00398 #ifndef H5O_SHARED_TYPE
00399 #error "Need to define H5O_SHARED_TYPE macro!"
00400 #endif /* H5O_SHARED_TYPE */
00401 #ifndef H5O_SHARED_POST_COPY_FILE
00402 #error "Need to define H5O_SHARED_POST_COPY_FILE macro!"
00403 #endif /* H5O_SHARED_POST_COPY_FILE */
00404 
00405 #ifdef H5O_SHARED_POST_COPY_FILE_REAL
00406     /* Call native message's copy file callback to copy the message */
00407     if(H5O_SHARED_POST_COPY_FILE_REAL(oloc_src, mesg_src, oloc_dst, mesg_dst, dxpl_id, cpy_info) <0 )
00408         HGOTO_ERROR(H5E_OHDR, H5E_CANTCOPY, FAIL, "unable to copy native message to another file")
00409 #endif /* H5O_SHARED_POST_COPY_FILE_REAL */
00410 
00411     /* update only shared message after the post copy */
00412     if(H5O_msg_is_shared(shared_dst->msg_type_id, mesg_dst)) {
00413         if(H5O_shared_post_copy_file(oloc_dst->file, dxpl_id, cpy_info->oh_dst, mesg_dst) < 0)
00414             HGOTO_ERROR(H5E_OHDR, H5E_WRITEERROR, FAIL, "unable to fix shared message in post copy")
00415     }
00416 
00417 done:
00418     FUNC_LEAVE_NOAPI(ret_value)
00419 } /* end H5O_SHARED_POST_COPY_FILE() */
00420 
00421 
00422 /*-------------------------------------------------------------------------
00423  * Function:    H5O_SHARED_DEBUG
00424  *
00425  * Purpose:     Prints debugging info for a potentially shared message.
00426  *
00427  * Note:        The actual name of this routine can be different in each source
00428  *              file that this header file is included in, and must be defined
00429  *              prior to including this header file.
00430  *
00431  * Return:      Success:        Non-negative
00432  *              Failure:        Negative
00433  *
00434  * Programmer:  Quincey Koziol
00435  *              Saturday, February  3, 2007
00436  *
00437  *-------------------------------------------------------------------------
00438  */
00439 static H5_inline herr_t
00440 H5O_SHARED_DEBUG(H5F_t *f, hid_t dxpl_id, const void *_mesg, FILE *stream,
00441     int indent, int fwidth)
00442 {
00443     const H5O_shared_t *sh_mesg = (const H5O_shared_t *)_mesg;     /* Pointer to shared message portion of actual message */
00444     herr_t ret_value = SUCCEED;           /* Return value */
00445 
00446     FUNC_ENTER_NOAPI_NOINIT(H5O_SHARED_DEBUG)
00447 
00448 #ifndef H5O_SHARED_TYPE
00449 #error "Need to define H5O_SHARED_TYPE macro!"
00450 #endif /* H5O_SHARED_TYPE */
00451 #ifndef H5O_SHARED_DEBUG
00452 #error "Need to define H5O_SHARED_DEBUG macro!"
00453 #endif /* H5O_SHARED_DEBUG */
00454 #ifndef H5O_SHARED_DEBUG_REAL
00455 #error "Need to define H5O_SHARED_DEBUG_REAL macro!"
00456 #endif /* H5O_SHARED_DEBUG_REAL */
00457 
00458     /* Check for message stored elsewhere */
00459     if(H5O_IS_STORED_SHARED(sh_mesg->type)) {
00460         /* Print shared message information */
00461         if(H5O_shared_debug(sh_mesg, stream, indent, fwidth) < 0)
00462             HGOTO_ERROR(H5E_OHDR, H5E_WRITEERROR, FAIL, "unable to display shared message info")
00463     } /* end if */
00464 
00465     /* Call native message's debug callback */
00466     if(H5O_SHARED_DEBUG_REAL(f, dxpl_id, _mesg, stream, indent, fwidth) < 0)
00467         HGOTO_ERROR(H5E_OHDR, H5E_WRITEERROR, FAIL, "unable to display native message info")
00468 
00469 done:
00470     FUNC_LEAVE_NOAPI(ret_value)
00471 } /* end H5O_SHARED_DEBUG() */
00472 
00473 #endif /* H5Oshared_H */
00474