mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-23 16:20:57 +08:00
[svn-r7937] Purpose:
Add RM docs for new H5I routines.
Description:
Add new H5I routines to the reference manual.
This commit is contained in:
Quincey Koziol
parent
16be9e3b5a
commit
38af6a43fa
@ -78,20 +78,53 @@ object names.
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Identify-IncRef">H5Iinc_ref</a>
|
||||
<li><a href="#Identify-GetName">H5Iget_name</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Identify-DecRef">H5Idec_ref</a>
|
||||
<li><a href="#Identify-GetType">H5Iget_type</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
|
||||
<li><a href="#Identify-GetRef">H5Iget_ref</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
<br>
|
||||
|
||||
|
||||
<i>Alphabetical Listing</i>
|
||||
|
||||
<table border="0">
|
||||
<tr>
|
||||
<td valign="top">
|
||||
<ul>
|
||||
<li><a href="#Identify-DecRef">H5Idec_ref</a>
|
||||
<li><a href="#Identify-GetName">H5Iget_name</a>
|
||||
</ul>
|
||||
</td>
|
||||
|
||||
<td> </td>
|
||||
|
||||
<td valign="top">
|
||||
<ul>
|
||||
<li><a href="#Identify-GetRef">H5Iget_ref</a>
|
||||
<li><a href="#Identify-GetType">H5Iget_type</a>
|
||||
</ul>
|
||||
</td>
|
||||
|
||||
<td> </td>
|
||||
|
||||
<td valign="top">
|
||||
<ul>
|
||||
<li><a href="#Identify-IncRef">H5Iinc_ref</a>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<br>
|
||||
<strong>The FORTRAN90 Interfaces:</strong>
|
||||
<br>
|
||||
@ -102,19 +135,95 @@ as the corresponding C function.
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Identify-IncRef">h5iinc_ref_f</a>
|
||||
<li><a href="#Identify-GetName">h5iget_name_f</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Identify-DecRef">h5idec_ref_f</a>
|
||||
<li><a href="#Identify-GetType">h5iget_type_f</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
|
||||
<li><a href="#Identify-GetRef">h5iget_ref_f</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<!-- HEADER RIGHT "H5Idec_ref" -->
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Identify-DecRef">H5Idec_ref</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Idec_ref</code>(<em>hid_t</em> <code>obj_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Decrements the reference count for an object.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Idec_ref</code> decrements the reference count of the object
|
||||
identified by <code>obj_id</code>.
|
||||
|
||||
<p>
|
||||
The reference count for an object ID is attached to the information
|
||||
about an object in memory and has no relation to the number of links to
|
||||
an object on disk.
|
||||
|
||||
<p>
|
||||
The reference count for a newly created object will be 1.
|
||||
Reference counts for objects may be explicitly modified with this
|
||||
function or with <code>H5Iinc_ref</code>.
|
||||
When an object ID's reference count reaches zero, the object will be
|
||||
closed.
|
||||
Calling an object ID's 'close' function decrements the reference count
|
||||
for the ID which normally closes the object, but
|
||||
if the reference count for the ID has been incremented with
|
||||
<code>H5Iinc_ref</code>, the object will only be closed when the
|
||||
reference count
|
||||
reaches zero with further calls to this function or the
|
||||
object ID's 'close' function.
|
||||
|
||||
<p>
|
||||
If the object ID was created by a collective parallel call (such as
|
||||
<code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference
|
||||
count should be modified by all the processes which have copies of
|
||||
the ID. Generally this means that group, dataset, attribute, file
|
||||
and named datatype IDs should be modified by all the processes and
|
||||
that all other types of IDs are safe to modify by individual processes.
|
||||
|
||||
<p>
|
||||
This function is of particular value when an application is maintaining
|
||||
multiple copies of an object ID. The object ID can be incremented when
|
||||
a copy is made. Each copy of the ID can then be safely closed or
|
||||
decremented and the HDF5 object will be closed when the reference count
|
||||
for that that object drops to zero.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>obj_id</code>
|
||||
<dd>IN: Object identifier whose reference count will be modified.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a non-negative reference count of the object ID after
|
||||
decrementing it if successful; otherwise a negative value is returned.
|
||||
<dt><strong>Fortran90 Interface:</strong> h5idec_ref_f
|
||||
<dd>
|
||||
<pre>
|
||||
SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr)
|
||||
IMPLICIT NONE
|
||||
INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
|
||||
INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
|
||||
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
||||
! 0 on success, and -1 on failure
|
||||
END SUBROUTINE h5idec_ref_f
|
||||
</pre>
|
||||
|
||||
<!--<dt><strong>Non-C API(s):</strong>
|
||||
<dd>
|
||||
|
||||
<img src="Graphics/Java.gif">
|
||||
<img src="Graphics/C++.gif">
|
||||
-->
|
||||
</dl>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<!-- NEW PAGE -->
|
||||
<!-- HEADER RIGHT "H5Iget_name" -->
|
||||
@ -189,6 +298,56 @@ END SUBROUTINE h5iget_name_f
|
||||
-->
|
||||
</dl>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<!-- HEADER RIGHT "H5Iget_ref" -->
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Identify-GetRef">H5Iget_ref</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Iget_ref</code>(<em>hid_t</em> <code>obj_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Retrieves the reference count for an object.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Iget_ref</code> retrieves the reference count of the object
|
||||
identified by <code>obj_id</code>.
|
||||
|
||||
<p>
|
||||
The reference count for an object ID is attached to the information
|
||||
about an object in memory and has no relation to the number of links to
|
||||
an object on disk.
|
||||
|
||||
<p>
|
||||
This function can also be used to check if an object ID is still valid.
|
||||
A non-negative return value from this function indicates that the ID
|
||||
is still valid.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>obj_id</code>
|
||||
<dd>IN: Object identifier whose reference count will be retrieved.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a non-negative current reference count of the object ID
|
||||
if successful; otherwise a negative value is returned.
|
||||
<dt><strong>Fortran90 Interface:</strong> h5iget_ref_f
|
||||
<dd>
|
||||
<pre>
|
||||
SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr)
|
||||
IMPLICIT NONE
|
||||
INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
|
||||
INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
|
||||
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
||||
! 0 on success, and -1 on failure
|
||||
END SUBROUTINE h5iget_ref_f
|
||||
</pre>
|
||||
|
||||
<!--<dt><strong>Non-C API(s):</strong>
|
||||
<dd>
|
||||
|
||||
<img src="Graphics/Java.gif">
|
||||
<img src="Graphics/C++.gif">
|
||||
-->
|
||||
</dl>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<!-- HEADER RIGHT "H5Iget_type" -->
|
||||
<hr>
|
||||
@ -264,6 +423,79 @@ END SUBROUTINE h5iget_type_f
|
||||
-->
|
||||
</dl>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<!-- HEADER RIGHT "H5Iinc_ref" -->
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Identify-IncRef">H5Iinc_ref</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Iinc_ref</code>(<em>hid_t</em> <code>obj_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Increments the reference count for an object.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Iinc_ref</code> increments the reference count of the object
|
||||
identified by <code>obj_id</code>.
|
||||
|
||||
<p>
|
||||
The reference count for an object ID is attached to the information
|
||||
about an object in memory and has no relation to the number of links to
|
||||
an object on disk.
|
||||
|
||||
<p>
|
||||
The reference count for a newly created object will be 1.
|
||||
Reference counts for objects may be explicitly modified with this
|
||||
function or with <code>H5Idec_ref</code>.
|
||||
When an object ID's reference count reaches zero, the object will be
|
||||
closed.
|
||||
Calling an object ID's 'close' function decrements the reference count
|
||||
for the ID which normally closes the object, but
|
||||
if the reference count for the ID has been incremented with this
|
||||
function, the object will only be closed when the reference count
|
||||
reaches zero with further calls to <code>H5Idec_ref</code> or the
|
||||
object ID's 'close' function.
|
||||
|
||||
<p>
|
||||
If the object ID was created by a collective parallel call (such as
|
||||
<code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference
|
||||
count should be modified by all the processes which have copies of
|
||||
the ID. Generally this means that group, dataset, attribute, file
|
||||
and named datatype IDs should be modified by all the processes and
|
||||
that all other types of IDs are safe to modify by individual processes.
|
||||
|
||||
<p>
|
||||
This function is of particular value when an application is maintaining
|
||||
multiple copies of an object ID. The object ID can be incremented when
|
||||
a copy is made. Each copy of the ID can then be safely closed or
|
||||
decremented and the HDF5 object will be closed when the reference count
|
||||
for that that object drops to zero.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>obj_id</code>
|
||||
<dd>IN: Object identifier whose reference count will be modified.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a non-negative reference count of the object ID after
|
||||
incrementing it if successful; otherwise a negative value is returned.
|
||||
<dt><strong>Fortran90 Interface:</strong> h5iinc_ref_f
|
||||
<dd>
|
||||
<pre>
|
||||
SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr)
|
||||
IMPLICIT NONE
|
||||
INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
|
||||
INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
|
||||
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
||||
! 0 on success, and -1 on failure
|
||||
END SUBROUTINE h5iinc_ref_f
|
||||
</pre>
|
||||
|
||||
<!--<dt><strong>Non-C API(s):</strong>
|
||||
<dd>
|
||||
|
||||
<img src="Graphics/Java.gif">
|
||||
<img src="Graphics/C++.gif">
|
||||
-->
|
||||
</dl>
|
||||
|
||||
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
||||
<center>
|
||||
<table border=0 width=98%>
|
||||
@ -304,7 +536,7 @@ And in this document, the
|
||||
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
|
||||
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
|
||||
<!--
|
||||
document.writeln("Last modified: 21 October 2003");
|
||||
document.writeln("Last modified: 11 December 2003");
|
||||
-->
|
||||
</SCRIPT>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user