[h5py] 84/455: Introduce info.txt; auto-import highlevel objects in h5py __init__
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:20 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to annotated tag 1.3.0
in repository h5py.
commit 8d25f85c099107d2ac0532638b278b7f2046605a
Author: andrewcollette <andrew.collette at gmail.com>
Date: Sat Jul 26 22:04:30 2008 +0000
Introduce info.txt; auto-import highlevel objects in h5py __init__
---
docs/info.txt | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
h5py/__init__.py | 5 +++-
h5py/h5.pyx | 2 +-
setup.py | 14 +++++++----
4 files changed, 89 insertions(+), 7 deletions(-)
diff --git a/docs/info.txt b/docs/info.txt
new file mode 100644
index 0000000..3109a80
--- /dev/null
+++ b/docs/info.txt
@@ -0,0 +1,75 @@
+
+
+Threading
+=========
+
+All h5py routines are thread-safe in the sense that they are implemented in
+C, and (with a few exceptions) hold the global intepreter lock until they
+finish. From the standpoint of a Python programmer, they are atomic operations;
+the execution of all threads blocks until they complete. This means you
+can call the same method on the same object from two different threads, and the
+two calls will execute serially without interfering with one another.
+
+Additionally, each ObjectID instance provides a reentrant lock via the property
+"pylock". If you acquire this lock, the HDF5 structure you've got hold of
+is guaranteed not to be modified by another thread until you release it. This
+is the case even your HDF5 structure is "pointed to" by different ObjectID
+instances.
+
+Non-Blocking Routines
+---------------------
+
+A few methods will release the global interpreter lock around I/O operations
+which can take a long time to complete. These methods always acquire their
+own "pylock" lock before beginning. They are still thread-safe in that
+multiple threads attempting to run the same routine will execute serially,
+although threads that do other things can run unimpeded.
+
+The following operations will release the GIL:
+
+ * DatasetID.read
+ * DatasetID.write
+
+Customizing Locks
+-----------------
+
+Because applications that use h5py may have their own threading systems, the
+type of lock used is settable at runtime. The settable property
+h5.config.RLock determines the lock class used. This can be set to any
+callable which produces a reentrant lock. It must implement the following
+methods:
+
+ __enter__(), __exit__() For the Python context manager protocol
+ acquire(), release() For manual lock management
+
+The default lock type is the native Python threading.RLock, but h5py makes no
+assumptions about the behavior or implementation of locks beyond reentrance and
+the existence of the four required methods above.
+
+ObjectID Hashing
+----------------
+
+H5py uses a global weak-reference dictionary to keep track of which lock goes
+with which ObjectID instance. For this to work, there must be a way to
+identify which ObjectID instances point to the same HDF5 structure. Two rules
+make this possible:
+
+ A. ObjectID instances which point to the same HDF5 structure must both
+ have the same hash() value.
+ B. ObjectID instances which point to the same HDF5 structure must evauluate
+ as equal.
+
+For named objects like datasets, groups, and files, the hash is derived from
+properties like fileno and objno, which are guaranteed by the library to be
+unique among open files. For all other objects, the HDF5 identifier determines
+uniqueness.
+
+
+
+
+
+
+
+
+
+
diff --git a/h5py/__init__.py b/h5py/__init__.py
index 7cdbf48..f02274a 100644
--- a/h5py/__init__.py
+++ b/h5py/__init__.py
@@ -24,7 +24,10 @@ __doc__ = \
import utils, h5, h5a, h5d, h5f, h5g, h5i, h5p, h5r, h5s, h5t, h5z, highlevel
+from highlevel import File, Group, Dataset, Datatype, AttributeManager
+
__doc__ = __doc__ % (h5.version, h5.hdf5_version, h5.api_version)
__all__ = ['h5', 'h5f', 'h5g', 'h5s', 'h5t', 'h5d', 'h5a', 'h5p',
- 'h5z', 'h5i', 'highlevel']
+ 'h5z', 'h5i', 'File', 'Group', 'Dataset',
+ 'Datatype', 'AttributeManager']
diff --git a/h5py/h5.pyx b/h5py/h5.pyx
index af5d0e1..69b808e 100644
--- a/h5py/h5.pyx
+++ b/h5py/h5.pyx
@@ -193,7 +193,7 @@ cdef class ObjectID:
property pylock:
""" RLock or equivalent for threads. The same lock is returned for
- equal objects (objects which point to the same HDF5 structure).
+ objects which point to the same HDF5 structure.
"""
def __get__(self):
if self._cfg is None:
diff --git a/setup.py b/setup.py
index b058fe2..2bc7a63 100644
--- a/setup.py
+++ b/setup.py
@@ -303,10 +303,11 @@ class dev(Command):
def run(self):
if self.clean:
- try:
- shutil.rmtree('build')
- except OSError:
- pass
+ for x in ('build','docs/html'):
+ try:
+ shutil.rmtree(x)
+ except OSError:
+ pass
fnames = [ x+'.dep' for x in pyrex_sources ] + \
[ x+'.c' for x in pyrex_sources ] + \
[ 'MANIFEST']
@@ -320,9 +321,12 @@ class dev(Command):
if self.doc:
buildobj = self.distribution.get_command_obj('build')
buildobj.run()
+ if not os.path.exists('docs/html'):
+ os.mkdir('docs', 0755)
+ os.mkdir('docs/html', 0755)
retval = os.spawnlp(os.P_WAIT, 'epydoc', '-q', '--html',
- '-o', 'docs/', '--config', 'docs.cfg',
+ '-o', 'docs/html', '--config', 'docs.cfg',
os.path.join(buildobj.build_lib, NAME) )
if retval != 0:
raise DistutilsExecError("Could not run epydoc to build documentation.")
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git
More information about the debian-science-commits
mailing list