Add new H5R API that abstracts object, region and attribute reference types

Also support references to external files

Add new H5T_REF type and type conversion routines

Support conversion from H5T_REF_OBJ/DSET_REG to H5T_REF

Add H5Treclaim() API to reclaim memory of vlen/reference types

Deprecate H5Dvlen_reclaim()

Fix H5T_vlen_reclaim() and H5T_reclaim() to use private callback

Add H5T_ref_reclaim()

Move previous H5R APIs to H5Rdeprec.c

Clean up H5Ocopy

Separate H5O_copy_expand_ref() to H5Ocopy_ref()

Add support for copying new reference types

Clean up deprecated routines to go through VOL and same code path

Fix return codes in existing trefer.c test

Rename trefer.c to trefer_deprec.c

trefer.c is for new references

Add performance test for trefer

Add additional obj_copy_ref test

Make use of tokens and blobs to store references

Skip blob encoding for object references

Start adding new reference examples

1 files changed, 75 insertions, 31 deletions

diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h
index 598bafd..ce54ac4 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -26,47 +26,64 @@
 /* Public Macros */
 /*****************/
 
-/* Note! Be careful with the sizes of the references because they should really
- * depend on the run-time values in the file.  Unfortunately, the arrays need
- * to be defined at compile-time, so we have to go with the worst case sizes
- * for them.  -QAK
- */
+/* Deprecated reference buffer sizes that are kept for backward compatibility */
 #define H5R_OBJ_REF_BUF_SIZE        sizeof(haddr_t)
+#define H5R_DSET_REG_REF_BUF_SIZE   (sizeof(haddr_t) + 4)
 
-/* 4 is used instead of sizeof(int) to permit portability between the Crays
- * and other machines (the heap ID is always encoded as an int32 anyway).
+/* Default reference buffer size.
+ * Note! Be careful with the sizes of the references because they should really
+ * depend on the run-time values in the file.
  */
-#define H5R_DSET_REG_REF_BUF_SIZE   (sizeof(haddr_t) + 4)
+#define H5R_REF_BUF_SIZE            (64)
 
 /*******************/
 /* Public Typedefs */
 /*******************/
 
-/* Reference types */
-typedef enum H5R_type_t {
-    H5R_BADTYPE     =   (-1),   /* Invalid Reference Type               */
-    H5R_OBJECT,                 /* Object reference                     */
-    H5R_DATASET_REGION,         /* Dataset Region Reference             */
-    H5R_MAXTYPE                 /* Highest type (Invalid as true type)  */
+/*
+ * Reference types allowed.
+ * DO NOT CHANGE THE ORDER or VALUES as reference type values are encoded into
+ * the datatype message header.
+ */
+typedef enum {
+    H5R_BADTYPE     =   (-1),   /* Invalid reference type           */
+    H5R_OBJECT1     =     0,    /* Backward compatibility (object)  */
+    H5R_DATASET_REGION1 = 1,    /* Backward compatibility (region)  */
+    H5R_OBJECT2         = 2,    /* Object reference                 */
+    H5R_DATASET_REGION2 = 3,    /* Region reference                 */
+    H5R_ATTR            = 4,    /* Attribute Reference              */
+    H5R_MAXTYPE         = 5     /* Highest type (invalid)           */
 } H5R_type_t;
 
-/* Object reference structure for user's code
- * This needs to be large enough to store largest haddr_t on a worst case
- * machine (8 bytes currently).
+/* Deprecated types are kept for backward compatibility with previous versions */
+
+/**
+ * Deprecated object reference type that is used with deprecated reference APIs.
+ * Note! This type can only be used with the "native" HDF5 VOL connector.
  */
 typedef haddr_t hobj_ref_t;
 
-/* Dataset Region reference structure for user's code
+/**
+ * Dataset region reference type that is used with deprecated reference APIs.
  * (Buffer to store heap ID and index)
  * This needs to be large enough to store largest haddr_t in a worst case
- * machine (8 bytes currently) plus an int
+ * machine (8 bytes currently) plus an int.
+ * Note! This type can only be used with the "native" HDF5 VOL connector.
  */
 typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE];
 
+/**
+ * Opaque reference type. The same reference type is used for object,
+ * dataset region and attribute references. This is the type that
+ * should always be used with the current reference API.
+ */
+typedef unsigned char H5R_ref_t[H5R_REF_BUF_SIZE];
+
 /********************/
 /* Public Variables */
 /********************/
 
+
 /*********************/
 /* Public Prototypes */
 /*********************/
@@ -75,30 +92,57 @@ typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE];
 extern "C" {
 #endif
 
-H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name,
-			 H5R_type_t ref_type, hid_t space_id);
-H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref);
-H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref);
-H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref,
-    H5O_type_t *obj_type);
-H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref,
-    char *name /*out*/, size_t size);
+/* Constructors */
+H5_DLL herr_t   H5Rcreate_object(hid_t loc_id, const char *name, H5R_ref_t *ref_ptr);
+H5_DLL herr_t   H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, H5R_ref_t *ref_ptr);
+H5_DLL herr_t   H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, H5R_ref_t *ref_ptr);
+H5_DLL herr_t   H5Rdestroy(H5R_ref_t *ref_ptr);
+
+/* Info */
+H5_DLL H5R_type_t   H5Rget_type(const H5R_ref_t *ref_ptr);
+H5_DLL htri_t   H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr);
+H5_DLL herr_t   H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr);
+
+/* Dereference */
+H5_DLL hid_t    H5Ropen_object(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+H5_DLL hid_t    H5Ropen_region(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+H5_DLL hid_t    H5Ropen_attr(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id);
+
+/* Get type */
+H5_DLL herr_t   H5Rget_obj_type3(const H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type);
+
+/* Get name */
+H5_DLL ssize_t  H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf, size_t size);
+H5_DLL ssize_t  H5Rget_obj_name(const H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size);
+H5_DLL ssize_t  H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf, size_t size);
 
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
  *
- * Use of these symbols is deprecated.
+ * Use of these symbols is or will be deprecated.
  */
-#ifndef H5_NO_DEPRECATED_SYMBOLS
+
+/* Macros */
+
+/* Versions for compatibility */
+#define H5R_OBJECT          H5R_OBJECT1
+#define H5R_DATASET_REGION  H5R_DATASET_REGION1
 
 /* Function prototypes */
-H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *_ref);
+#ifndef H5_NO_DEPRECATED_SYMBOLS
+
+H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref);
 H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref);
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */
 
+H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id);
+H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type);
+H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref);
+H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref);
+H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size);
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif  /* _H5Rpublic_H */
-