summaryrefslogtreecommitdiffstats
path: root/src/H5I.c
blob: 6b9383c871795cae7f83fa4d6278d46724335030 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
/****************************************************************************
 * NCSA HDF								    *
 * Software Development Group						    *
 * National Center for Supercomputing Applications			    *
 * University of Illinois at Urbana-Champaign				    *
 * 605 E. Springfield, Champaign IL 61820				    *
 *									    *
 * For conditions of distribution and use, see the accompanying		    *
 * hdf/COPYING file.							    *
 *									    *
 ****************************************************************************/

#ifdef RCSID
static char		RcsId[] = "@(#)$Revision$";
#endif

/* $Id$ */

/*
   FILE
   H5I.c - Internal storage routines for handling "IDs"

   REMARKS
   ID's which allow objects (void *'s currently) to be bundled into "groups"
   for more general storage.

   DESIGN
   The groups are stored in an array of pointers to store each group in an
   element. Each "group" node contains a link to a hash table to manage the IDs
   in each group.  The allowed "groups" are stored in an enum (called group_t)
   in H5Ipublic.h.

   BUGS/LIMITATIONS
   Can't interate over the IDs in a group.

   LOCAL ROUTINES
   H5I_find_id      - Returns a pointer to an HAI_id_info_t from an ID
   H5I_get_id_node  - Gets an ID node (uses the ID free list)
   H5I_release_id_node - Releases an ID node (uses the ID free list)
   EXPORTED ROUTINES
   ID Functions:
   H5I_register	      - Register an object in a group and get an ID for it
   H5I_object	      - Get the object for an ID
   H5I_group	      - Get the group for an ID
   H5I_remove	      - Remove an ID from a group
   H5I_search	      - Search a group for a particular object
   ID Group Functions:
   H5I_init_group      - Initialize a group to store IDs in
   H5I_destroy_group   - Destroy an ID group
   ID Group Cleanup:
   H5Ishutdown	      - Terminate various static buffers.

   AUTHOR
   Quincey Koziol

   MODIFICATION HISTORY
   1/3/96  - Starting writing specs & coding prototype
   1/7/96  - Finished coding prototype
   6/10/97 - Moved into HDF5 library
 */

#include <H5private.h>
#include <H5Iprivate.h>
#include <H5Eprivate.h>
#include <H5MMprivate.h>

#define PABLO_MASK	H5I_mask

/*-------------------- Locally scoped variables -----------------------------*/

#ifdef IDS_ARE_CACHED
/* Array of pointers to ID groups */
static hid_t H5I_id_cache[ID_CACHE_SIZE] = {-1, -1, -1, -1};
static void *H5I_obj_cache[ID_CACHE_SIZE];
#endif

/* Array of pointers to atomic groups */
static H5I_id_group_t *id_group_list[MAXGROUP];

/* Pointer to the atom node free list */
static H5I_id_info_t *id_free_list = NULL;

/* Interface initialialization? */
static hbool_t interface_initialize_g = FALSE;
#define INTERFACE_INIT H5I_init_interface
static herr_t H5I_init_interface(void);

/*--------------------- Local function prototypes ---------------------------*/
static H5I_id_info_t *H5I_find_id(hid_t id);
static H5I_id_info_t *H5I_get_id_node(void);
static herr_t H5I_release_id_node(H5I_id_info_t *id);


/*--------------------------------------------------------------------------
NAME
   H5I_init_interface -- Initialize interface-specific information
USAGE
    herr_t H5I_init_interface()
RETURNS
   SUCCEED/FAIL
DESCRIPTION
    Initializes any interface-specific data or routines.
--------------------------------------------------------------------------*/
static herr_t 
H5I_init_interface(void)
{
    herr_t		    ret_value = SUCCEED;
    FUNC_ENTER(H5I_init_interface, FAIL);

    /* Registers the cleanup routine with the exit chain */
    ret_value = H5_add_exit(&H5I_term_interface);

    FUNC_LEAVE(ret_value);
}


/******************************************************************************
 NAME
     H5I_init_group - Initialize an ID group

 DESCRIPTION
    Creates a global ID group to store IDs in.  If the group has already
    been initialized, this routine just increments the count of # of
    initializations and returns without trying to change the size of the hash
    table.  A specific number of group entries may be reserved to enable
    "constant" values to be handed out which are valid IDs in the group, but
    which do not map to any data structures and are not allocated dynamicly
    later.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

******************************************************************************/
intn 
H5I_init_group(H5I_group_t grp,	 /* IN: Group to initialize */
	       size_t hash_size, /* IN: Minimum hash table size to use for group */
	       uintn reserved,	 /* IN: Number of hash table entries to reserve */
	       herr_t (*free_func) (void *)	/* IN: Function to call when releasing ref counted objects */
)
{
    H5I_id_group_t	   *grp_ptr = NULL;	/* ptr to the atomic group */
    intn		    ret_value = SUCCEED;

    FUNC_ENTER(H5I_init_group, FAIL);

    if ((grp <= BADGROUP || grp >= MAXGROUP) && hash_size > 0) {
	HGOTO_DONE(FAIL);
    }

#ifdef HASH_SIZE_POWER_2
    /*
     * If anyone knows a faster test for a power of two, please change this
     * silly code -QAK
     */
    if (!(hash_size == 2 || hash_size == 4 || hash_size == 8 ||
	  hash_size == 16 || hash_size == 32 || hash_size == 64 ||
	  hash_size == 128 || hash_size == 256 || hash_size == 512 ||
	  hash_size == 1024 || hash_size == 2048 || hash_size == 4096 ||
	  hash_size == 8192 || hash_size == 16374 || hash_size == 32768 ||
	  hash_size == 65536 || hash_size == 131072 || hash_size == 262144 ||
	  hash_size == 524288 || hash_size == 1048576 ||
	  hash_size == 2097152 || hash_size == 4194304 ||
	  hash_size == 8388608 || hash_size == 16777216 ||
	  hash_size == 33554432 || hash_size == 67108864 ||
	  hash_size == 134217728 || hash_size == 268435456))
	HGOTO_DONE(FAIL);
#endif /* HASH_SIZE_POWER_2 */

    if (id_group_list[grp] == NULL) {
	/* Allocate the group information */
	grp_ptr = H5MM_xcalloc(1, sizeof(H5I_id_group_t));
	id_group_list[grp] = grp_ptr;
    } else {
	/* Get the pointer to the existing group */
	grp_ptr = id_group_list[grp];
    }

    if (grp_ptr->count == 0) {
	/* Initialize the ID group structure */
	grp_ptr->hash_size = hash_size;
	grp_ptr->reserved = reserved;
	grp_ptr->wrapped = 0;
	grp_ptr->ids = 0;
	grp_ptr->nextid = reserved;
	grp_ptr->free_func = free_func;
	grp_ptr->id_list = H5MM_xcalloc((intn)hash_size,
					sizeof(H5I_id_info_t *));
    }
    
    /* Increment the count of the times this group has been initialized */
    grp_ptr->count++;

  done:
    if (ret_value == FAIL) {
	/* Error condition cleanup */
	if (grp_ptr != NULL) {
	    H5MM_xfree (grp_ptr->id_list);
	    H5MM_xfree (grp_ptr);
	}
    }
    
    /* Normal function cleanup */
    FUNC_LEAVE(ret_value);
}


/*-------------------------------------------------------------------------
 * Function:	H5I_destroy_group
 *
 * Purpose:	Decrements the reference count on an entire group of IDs.
 *		If the group reference count becomes zero then the group is
 *		destroyed along with all atoms in that group regardless of
 *		their reference counts.  Destroying IDs involves calling
 *		the free-func for each ID's object and then adding the ID
 *		struct to the ID free list.
 *		
 * Return:	Success:	SUCCEED
 *
 *		Failure:	FAIL
 *
 * Programmer:	Unknown
 *
 * Modifications:
 *
 * 	Robb Matzke, 25 Feb 1998
 *	IDs are freed when a group is destroyed.
 *
 *-------------------------------------------------------------------------
 */
herr_t
H5I_destroy_group(H5I_group_t grp)
{
    H5I_id_group_t	*grp_ptr = NULL;	/* ptr to the atomic group */
    H5I_id_info_t	*cur=NULL, *next=NULL;
    intn		ret_value = SUCCEED;
    uintn		i;

    FUNC_ENTER(H5I_destroy_group, FAIL);

    if (grp <= BADGROUP || grp >= MAXGROUP)
	HGOTO_DONE(FAIL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0)
	HGOTO_DONE(FAIL);

    /*
     * Decrement the number of users of the atomic group.  If this is the
     * last user of the group then release all atoms from the group.  The
     * free function is invoked for each atom being freed.
     */
    if ((--(grp_ptr->count)) == 0) {

#ifdef IDS_ARE_CACHED
	/*
	 * Remove atoms from the global atom cache.
	 */
	for (i=0; i<ID_CACHE_SIZE; i++) {
	    if (ID_TO_GROUP(H5I_id_cache[i]) == grp) {
		H5I_id_cache[i] = (-1);
		H5I_obj_cache[i] = NULL;
	    }
	}
#endif /* IDS_ARE_CACHED */

	/*
	 * Free all objects.
	 */
	if (grp_ptr->free_func) {
	    for (i=0; i<grp_ptr->hash_size; i++) {
            for (cur=grp_ptr->id_list[i]; cur; cur=next) {
                /* Free the object */
                (grp_ptr->free_func)(cur->obj_ptr);

                /* Add ID struct to free list */
                next = cur->next;
                cur->next = id_free_list;
                id_free_list = cur;
            }
	    }
	}

	/* Free local cache and reset group */
	H5MM_xfree(grp_ptr->id_list);
	HDmemset (grp_ptr, 0, sizeof(grp_ptr));
    }
    
  done:
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_register - Register an object in a group and get an ID for it.

 DESCRIPTION
    Registers an object in a group and returns an ID for it.	This routine
    does _not_ check for unique-ness of the objects, if you register an object
    twice, you will get two different IDs for it.  This routine does make
    certain that each ID in a group is unique.  IDs are created by getting
    a unique number for the group the ID is in and incorporating the group
    into the ID which is returned to the user.

 RETURNS
    Returns ID if successful and FAIL otherwise

*******************************************************************************/
hid_t 
H5I_register(H5I_group_t grp,   /* IN: Group to register the object in */
	     void *object     /* IN: Object to attach to atom */
)
{
    H5I_id_group_t	   *grp_ptr = NULL;	/* ptr to the group */
    H5I_id_info_t	*id_ptr = NULL;	/* ptr to the new ID information */
    hid_t		    new_id;	/* new ID */
    uintn		    hash_loc;	/* new item's hash table location */
    hid_t		    ret_value = SUCCEED;

    FUNC_ENTER(H5I_register, FAIL);

    if (grp <= BADGROUP || grp >= MAXGROUP)
	HGOTO_DONE(FAIL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0)
	HGOTO_DONE(FAIL);

    if ((id_ptr = H5I_get_id_node()) == NULL)
	HGOTO_DONE(FAIL);

    /* Create the struct & it's ID */
    new_id = MAKE_ID(grp, grp_ptr->nextid);
    id_ptr->id = new_id;
    id_ptr->count = 1; /*initial reference count*/
    id_ptr->obj_ptr = object;
    id_ptr->next = NULL;

    /* hash bucket already full, prepend to front of chain */
    hash_loc = grp_ptr->nextid % (uintn) grp_ptr->hash_size;
    if (grp_ptr->id_list[hash_loc] != NULL)
	id_ptr->next = grp_ptr->id_list[hash_loc];

    /* Insert into the group */
    grp_ptr->id_list[hash_loc] = id_ptr;
    grp_ptr->ids++;
    grp_ptr->nextid++;

    /*
     * This next section of code checks for the 'nextid' getting too large and
     * wrapping around, thus necessitating checking for duplicate IDs being
     * handed out.
     */
    if (grp_ptr->nextid > (uintn) ID_MASK || grp_ptr->wrapped != 0) {
	if (grp_ptr->wrapped == 0) {
	    /* set the "wrapped around" flag if it isn't already */
	    grp_ptr->wrapped = 1;
	    /* re-start the ID counter */
	    grp_ptr->nextid = grp_ptr->reserved;
	}
	
	do {
	    /* new ID to check for */
	    hid_t next_id = MAKE_ID(grp, grp_ptr->nextid);
	    H5I_id_info_t *curr_id;   /* ptr to the current atom */
	    hash_loc = ID_TO_LOC (grp_ptr->nextid, grp_ptr->hash_size);

	    curr_id = grp_ptr->id_list[hash_loc];
	    if (curr_id == NULL) break; /* Ha! this is not likely... */

	    while (curr_id != NULL) {
		if (curr_id->id == next_id) break;
		curr_id = curr_id->next;
	    }
	    if (curr_id == NULL) break; /* must not have found a match */
	    grp_ptr->nextid++;
	} while (grp_ptr->nextid <= (uintn) ID_MASK);
	
	if (grp_ptr->nextid > (uintn) ID_MASK) {
	    /* All the IDs are gone! */
	    HGOTO_DONE(FAIL);
	}
    }
    ret_value = new_id;

  done:
    if (ret_value == FAIL) {
	/* Error condition cleanup */
    }
    
    /* Normal function cleanup */
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_inc_ref - Adds a reference to a reference counted ID.
	IN: ID to increment reference count for
 DESCRIPTION
    Increments the number of references outstanding for an ID.  This will
    fail if the group is not a reference counted group.

 RETURNS
    ID/FAIL

*******************************************************************************/
hid_t
H5I_inc_ref(hid_t id)
{
    H5I_group_t		grp = ID_TO_GROUP(id); /* object's group	*/
    H5I_id_group_t	*grp_ptr = NULL;	/* ptr to the ID group*/
    H5I_id_info_t		*id_ptr = NULL;	/* ptr to the new ID 	*/
    hid_t		ret_value = FAIL;

    FUNC_ENTER(H5I_inc_ref, FAIL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0 || grp_ptr->free_func == NULL) {
	HRETURN(FAIL);
    }
    
    /* General lookup of the atom */
    if (NULL!=(id_ptr = H5I_find_id(id))) {
	id_ptr->count++;
	ret_value = id;
    }
    
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_object - Returns to the object ptr for the ID 

 DESCRIPTION
    Retrieves the object ptr which is associated with the ID.

 RETURNS
    Returns object ptr if successful and NULL otherwise

*******************************************************************************/
void * 
H5I_object(hid_t id)
{
#ifdef IDS_ARE_CACHED
    uintn		i;	/* local counter */
#endif /* IDS_ARE_CACHED */
    H5I_id_info_t		*id_ptr = NULL;	/* ptr to the new atom */
    void 		*ret_value = NULL;

    FUNC_ENTER(H5I_object, NULL);

#ifdef IDS_ARE_CACHED
    /*
     * Look for the ID in the cache first. Implement a simple "move
     * forward" caching scheme by swapping the found cache item with the
     * previous cache item.  This gradually migrates used cache items toward
     * the front of the cache and unused items toward the end.  For instance,
     * finding `e' in the cache results in:
     *
     * Before: a b c d e f g h i j
     *	       | | |  X  | | | | |
     * After:  a b c e d f g h i j
     */
    for (i=0; i<ID_CACHE_SIZE; i++)
	if (H5I_id_cache[i] == id) {
	    ret_value = H5I_obj_cache[i];
	    if (i > 0) {
		hid_t t_id = H5I_id_cache[i-1];
		void *t_obj = H5I_obj_cache[i-1];
		H5I_id_cache[i-1] = H5I_id_cache[i];
		H5I_obj_cache[i-1] = H5I_obj_cache[i];
		H5I_id_cache[i] = t_id;
		H5I_obj_cache[i] = t_obj;
	    }
	    HGOTO_DONE(ret_value);
	}
#endif /* IDS_ARE_CACHED */

    /* General lookup of the ID */
    if ((id_ptr = H5I_find_id(id)) == NULL) HGOTO_DONE(NULL);

    /* Check if we've found the correct ID */
    if (id_ptr != NULL) ret_value = id_ptr->obj_ptr;

  done:
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_group - Returns to the group for the ID 

 DESCRIPTION
    Retrieves the group which is associated with the ID.

 RETURNS
    Returns group if successful and BADGROUP otherwise

*******************************************************************************/
H5I_group_t 
H5I_group(hid_t id)
{
    H5I_group_t		ret_value = BADGROUP;

    FUNC_ENTER(H5I_group, BADGROUP);

    ret_value = ID_TO_GROUP(id);
    if (ret_value <= BADGROUP || ret_value >= MAXGROUP) {
	HGOTO_DONE(BADGROUP);
    }
    

  done:
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_remove - Removes an ID from a group

 DESCRIPTION
    Removes an ID from a group.

 RETURNS
    Returns ID's object if successful and NULL otherwise

*******************************************************************************/
void * 
H5I_remove(hid_t id)
{
    H5I_id_group_t	*grp_ptr = NULL;/* ptr to the atomic group	*/
    H5I_id_info_t		*curr_id,	/* ptr to the current atom 	*/
			*last_id;	/* ptr to the last atom 	*/
    H5I_group_t		grp;		/* atom's atomic group 		*/
    uintn		hash_loc;	/* atom's hash table location 	*/
#ifdef IDS_ARE_CACHED
    uintn		i;		/* local counting variable 	*/
#endif
    void *	      ret_value = NULL;

    FUNC_ENTER(H5I_remove, NULL);

    grp = ID_TO_GROUP(id);
    if (grp <= BADGROUP || grp >= MAXGROUP) HGOTO_DONE(NULL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0) HGOTO_DONE(NULL);

    /* Get the location in which the ID is located */
    hash_loc = (uintn) ID_TO_LOC(id, grp_ptr->hash_size);
    curr_id = grp_ptr->id_list[hash_loc];
    if (curr_id == NULL) HGOTO_DONE(NULL);

    last_id = NULL;
    while (curr_id != NULL) {
	if (curr_id->id == id) break;
	last_id = curr_id;
	curr_id = curr_id->next;
    }

    if (curr_id != NULL) {
	if (last_id == NULL) {
	    /* ID is the first the chain */
	    grp_ptr->id_list[hash_loc] = curr_id->next;
	} else {
	    last_id->next = curr_id->next;
	}
	ret_value = curr_id->obj_ptr;
	H5I_release_id_node(curr_id);
    } else {
	/* couldn't find the ID in the proper place */
	HGOTO_DONE(NULL);
    }

#ifdef IDS_ARE_CACHED
    /* Delete object from cache */
    for (i = 0; i < ID_CACHE_SIZE; i++)
	if (H5I_id_cache[i] == id) {
	    H5I_id_cache[i] = (-1);
	    H5I_obj_cache[i] = NULL;
	    break; /* we assume there is only one instance in the cache */
	}
#endif /* IDS_ARE_CACHED */

    /* Decrement the number of IDs in the group */
    (grp_ptr->ids)--;

  done:
    FUNC_LEAVE(ret_value);
}


/*-------------------------------------------------------------------------
 * Function:	H5I_dec_ref
 *
 * Purpose:	Decrements the number of references outstanding for an ID.
 *		This will fail if the group is not a reference counted group.
 *		The ID group's 'free' function will be called for the ID
 *		if the reference count for the ID reaches 0 and a free
 *		function has been defined at group creation time.
 *
 * Return:	Success:	New reference count.
 *
 *		Failure:	FAIL
 *
 * Programmer:	Unknown
 *
 * Modifications:
 *
 *	Robb Matzke, 19 Feb 1998
 *	It is no longer an error when the reference count of an item reaches
 *	zero and no `free' function has been defined.  The object is still
 *	removed from the list.
 *
 *-------------------------------------------------------------------------
 */
intn
H5I_dec_ref(hid_t id)
{
    H5I_group_t		grp = ID_TO_GROUP(id); /* Group the object is in */
    H5I_id_group_t	*grp_ptr = NULL;     /* ptr to the group */
    H5I_id_info_t		*id_ptr = NULL;     /* ptr to the new ID */
    void *		obj;	    /* object to call 'free' function with */
    intn		ret_value = FAIL;

    FUNC_ENTER(H5I_dec_ref, FAIL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0) {
	HRETURN(FAIL);
    }
    
    /* General lookup of the ID */
    if ((id_ptr = H5I_find_id(id)) != NULL) {
	/* Decrement the reference count */
	ret_value = --(id_ptr->count);

	/* If the reference count is zero, remove the object from the group */
	if (0 == id_ptr->count && (obj = H5I_remove(id)) != NULL) {
	    /*
	     * call the user's 'free' function for the atom's information,
	     * otherwise just leak memory.
	     */
	    if (grp_ptr->free_func) {
		if ((grp_ptr->free_func)(obj)<0) {
		    HRETURN_ERROR (H5E_ATOM, H5E_CANTINIT, FAIL,
				   "unable to free atom");
		}
	    }
	}
	ret_value = SUCCEED;
    }
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_search - Search for an object in a group and get it's pointer.

 DESCRIPTION
    Searchs for an object in a group and returns the pointer to it.
    This routine calls the function pointer passed in for each object in the
    group until it finds a match.  Currently there is no way to resume a
    search.

 RETURNS
    Returns pointer an ID's object if successful and NULL otherwise

*******************************************************************************/
void *
H5I_search(H5I_group_t grp,	    /* IN: Group to search for the object in */
	   H5I_search_func_t func,   /* IN: Ptr to the comparison function */
	   const void *key  /* IN: pointer to key to compare against */
)
{
    H5I_id_group_t	   *grp_ptr = NULL;	/* ptr to the group */
    H5I_id_info_t		   *id_ptr = NULL;	/* ptr to the new ID */
    uintn		    i;	/* local counting variable */
    void *	      ret_value = NULL;

    FUNC_ENTER(H5I_search, NULL);

    if (grp <= BADGROUP || grp >= MAXGROUP)
	HGOTO_DONE(NULL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0)
	HGOTO_DONE(NULL);

    /* Start at the beginning of the array */
    for (i = 0; i < grp_ptr->hash_size; i++) {
	id_ptr = grp_ptr->id_list[i];
	while (id_ptr != NULL) {
	    if ((*func) (id_ptr->obj_ptr, key))
		HGOTO_DONE(id_ptr->obj_ptr);	/* found the item we are looking for */
	    id_ptr = id_ptr->next;
	}
    }

  done:
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_find_id - Finds a ID in a group

 DESCRIPTION
    Retrieves the ID ptr which is associated with the ID.

 RETURNS
    Returns ID ptr if successful and NULL otherwise

*******************************************************************************/
static H5I_id_info_t *
H5I_find_id(hid_t id)
{
    H5I_id_group_t	   *grp_ptr = NULL;	/* ptr to the group */
    H5I_id_info_t		   *id_ptr = NULL;	/* ptr to the new ID */
    H5I_group_t		    grp;	/* ID's group */
    uintn		    hash_loc;	/* ID's hash table location */
    H5I_id_info_t		   *ret_value = NULL;

    FUNC_ENTER(H5I_find_id, NULL);

    grp = ID_TO_GROUP(id);
    if (grp <= BADGROUP || grp >= MAXGROUP)
	HGOTO_DONE(NULL);

    grp_ptr = id_group_list[grp];
    if (grp_ptr == NULL || grp_ptr->count <= 0)
	HGOTO_DONE(NULL);

    /* Get the location in which the ID is located */
    hash_loc = (uintn) ID_TO_LOC(id, grp_ptr->hash_size);
    id_ptr = grp_ptr->id_list[hash_loc];
    if (id_ptr == NULL)
	HGOTO_DONE(NULL);

    while (id_ptr != NULL) {
	if (id_ptr->id == id) break;
	id_ptr = id_ptr->next;
    }
    ret_value = id_ptr;

#ifdef IDS_ARE_CACHED
    H5I_id_cache[ID_CACHE_SIZE-1] = id;
    H5I_obj_cache[ID_CACHE_SIZE-1] = id_ptr->obj_ptr;
#endif /* IDS_ARE_CACHED */

  done:
    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_get_idm_node - Gets an ID node

 DESCRIPTION
    Either gets an ID node from the free list (if there is one available)
    or allocate a node.

 RETURNS
    Returns ID ptr if successful and NULL otherwise

*******************************************************************************/
static H5I_id_info_t *
H5I_get_id_node(void)
{
    H5I_id_info_t		   *ret_value = NULL;

    FUNC_ENTER(H5I_get_id_node, NULL);

    if (id_free_list != NULL) {
	ret_value = id_free_list;
	id_free_list = id_free_list->next;
    } else {
	ret_value = H5MM_xmalloc(sizeof(H5I_id_info_t));
    }

    FUNC_LEAVE(ret_value);
}

/******************************************************************************
 NAME
     H5I_release_id_node - Releases an ID node

 DESCRIPTION
    Puts an ID node into the free list

 RETURNS
    SUCCEED

*******************************************************************************/
static herr_t
H5I_release_id_node(H5I_id_info_t *id)
{
    FUNC_ENTER(H5I_release_id_node, FAIL);

    /* Insert the ID at the beginning of the free list */
    id->next = id_free_list;
    id_free_list = id;

    FUNC_LEAVE(SUCCEED);
}

/*--------------------------------------------------------------------------
 NAME
    H5I_term_interface
 PURPOSE
    Terminate various static buffers.
 USAGE
    intn H5I_term_interface()
 RETURNS
    Returns SUCCEED/FAIL
 DESCRIPTION
    Free various buffers allocated in the H5I routines.
 GLOBAL VARIABLES
 COMMENTS, BUGS, ASSUMPTIONS
    Should only ever be called by the "atexit" function HDFend
 EXAMPLES
 REVISION LOG
--------------------------------------------------------------------------*/
void 
H5I_term_interface(void)
{
    H5I_id_info_t		   *curr;
    intn		    i;

    /* Release the free-list if it exists */
    if (id_free_list != NULL) {
	while (id_free_list != NULL) {
	    curr = id_free_list;
	    id_free_list = id_free_list->next;
	    HDfree(curr);
	}
    }

    /* Release all groups */
    for (i = 0; i < (intn) MAXGROUP; i++) {
	if (id_group_list[i] != NULL) {
	    HDfree(id_group_list[i]);
	    id_group_list[i] = NULL;
	}
    }
}