1 /*-------------------------------------------------------------------------
4 * Hash table page management code for the Postgres hash access method
6 * Portions Copyright (c) 1996-2006, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
11 * $PostgreSQL: pgsql/src/backend/access/hash/hashpage.c,v 1.57 2006/03/31 23:32:05 tgl Exp $
14 * Postgres hash pages look like ordinary relation pages. The opaque
15 * data at high addresses includes information about the page including
16 * whether a page is an overflow page or a true bucket, the bucket
17 * number, and the block numbers of the preceding and following pages
20 * The first page in a hash relation, page zero, is special -- it stores
21 * information describing the hash table; it is referred to as the
22 * "meta page." Pages one and higher store the actual data.
24 * There are also bitmap pages, which are not manipulated here;
27 *-------------------------------------------------------------------------
31 #include "access/genam.h"
32 #include "access/hash.h"
33 #include "miscadmin.h"
34 #include "storage/lmgr.h"
35 #include "utils/lsyscache.h"
38 static void _hash_splitbucket(Relation rel, Buffer metabuf,
39 Bucket obucket, Bucket nbucket,
40 BlockNumber start_oblkno,
41 BlockNumber start_nblkno,
43 uint32 highmask, uint32 lowmask);
47 * We use high-concurrency locking on hash indexes (see README for an overview
48 * of the locking rules). However, we can skip taking lmgr locks when the
49 * index is local to the current backend (ie, either temp or new in the
50 * current transaction). No one else can see it, so there's no reason to
51 * take locks. We still take buffer-level locks, but not lmgr locks.
53 #define USELOCKING(rel) (!RELATION_IS_LOCAL(rel))
57 * _hash_getlock() -- Acquire an lmgr lock.
59 * 'whichlock' should be zero to acquire the split-control lock, or the
60 * block number of a bucket's primary bucket page to acquire the per-bucket
61 * lock. (See README for details of the use of these locks.)
63 * 'access' must be HASH_SHARE or HASH_EXCLUSIVE.
66 _hash_getlock(Relation rel, BlockNumber whichlock, int access)
69 LockPage(rel, whichlock, access);
73 * _hash_try_getlock() -- Acquire an lmgr lock, but only if it's free.
75 * Same as above except we return FALSE without blocking if lock isn't free.
78 _hash_try_getlock(Relation rel, BlockNumber whichlock, int access)
81 return ConditionalLockPage(rel, whichlock, access);
87 * _hash_droplock() -- Release an lmgr lock.
90 _hash_droplock(Relation rel, BlockNumber whichlock, int access)
93 UnlockPage(rel, whichlock, access);
97 * _hash_getbuf() -- Get a buffer by block number for read or write.
99 * 'access' must be HASH_READ, HASH_WRITE, or HASH_NOLOCK.
101 * When this routine returns, the appropriate lock is set on the
102 * requested buffer and its reference count has been incremented
103 * (ie, the buffer is "locked and pinned").
105 * XXX P_NEW is not used because, unlike the tree structures, we
106 * need the bucket blocks to be at certain block numbers.
108 * All call sites should call either _hash_pageinit or _hash_checkpage
109 * on the returned page, depending on whether the block is expected
113 _hash_getbuf(Relation rel, BlockNumber blkno, int access)
118 elog(ERROR, "hash AM does not use P_NEW");
120 buf = ReadBuffer(rel, blkno);
122 if (access != HASH_NOLOCK)
123 LockBuffer(buf, access);
125 /* ref count and lock type are correct */
130 * _hash_relbuf() -- release a locked buffer.
132 * Lock and pin (refcount) are both dropped.
135 _hash_relbuf(Relation rel, Buffer buf)
137 UnlockReleaseBuffer(buf);
141 * _hash_dropbuf() -- release an unlocked buffer.
143 * This is used to unpin a buffer on which we hold no lock.
146 _hash_dropbuf(Relation rel, Buffer buf)
152 * _hash_wrtbuf() -- write a hash page to disk.
154 * This routine releases the lock held on the buffer and our refcount
155 * for it. It is an error to call _hash_wrtbuf() without a write lock
156 * and a pin on the buffer.
158 * NOTE: this routine should go away when/if hash indexes are WAL-ified.
159 * The correct sequence of operations is to mark the buffer dirty, then
160 * write the WAL record, then release the lock and pin; so marking dirty
161 * can't be combined with releasing.
164 _hash_wrtbuf(Relation rel, Buffer buf)
166 MarkBufferDirty(buf);
167 UnlockReleaseBuffer(buf);
171 * _hash_chgbufaccess() -- Change the lock type on a buffer, without
172 * dropping our pin on it.
174 * from_access and to_access may be HASH_READ, HASH_WRITE, or HASH_NOLOCK,
175 * the last indicating that no buffer-level lock is held or wanted.
177 * When from_access == HASH_WRITE, we assume the buffer is dirty and tell
178 * bufmgr it must be written out. If the caller wants to release a write
179 * lock on a page that's not been modified, it's okay to pass from_access
180 * as HASH_READ (a bit ugly, but handy in some places).
183 _hash_chgbufaccess(Relation rel,
188 if (from_access == HASH_WRITE)
189 MarkBufferDirty(buf);
190 if (from_access != HASH_NOLOCK)
191 LockBuffer(buf, BUFFER_LOCK_UNLOCK);
192 if (to_access != HASH_NOLOCK)
193 LockBuffer(buf, to_access);
198 * _hash_metapinit() -- Initialize the metadata page of a hash index,
199 * the two buckets that we begin with and the initial
202 * We are fairly cavalier about locking here, since we know that no one else
203 * could be accessing this index. In particular the rule about not holding
204 * multiple buffer locks is ignored.
207 _hash_metapinit(Relation rel)
210 HashPageOpaque pageopaque;
220 if (RelationGetNumberOfBlocks(rel) != 0)
221 elog(ERROR, "cannot initialize non-empty hash index \"%s\"",
222 RelationGetRelationName(rel));
225 * Determine the target fill factor (tuples per bucket) for this index.
226 * The idea is to make the fill factor correspond to pages about 3/4ths
227 * full. We can compute it exactly if the index datatype is fixed-width,
228 * but for var-width there's some guessing involved.
230 data_width = get_typavgwidth(RelationGetDescr(rel)->attrs[0]->atttypid,
231 RelationGetDescr(rel)->attrs[0]->atttypmod);
232 item_width = MAXALIGN(sizeof(IndexTupleData)) + MAXALIGN(data_width) +
233 sizeof(ItemIdData); /* include the line pointer */
234 ffactor = (BLCKSZ * 3 / 4) / item_width;
235 /* keep to a sane range */
239 metabuf = _hash_getbuf(rel, HASH_METAPAGE, HASH_WRITE);
240 pg = BufferGetPage(metabuf);
241 _hash_pageinit(pg, BufferGetPageSize(metabuf));
243 pageopaque = (HashPageOpaque) PageGetSpecialPointer(pg);
244 pageopaque->hasho_prevblkno = InvalidBlockNumber;
245 pageopaque->hasho_nextblkno = InvalidBlockNumber;
246 pageopaque->hasho_bucket = -1;
247 pageopaque->hasho_flag = LH_META_PAGE;
248 pageopaque->hasho_filler = HASHO_FILL;
250 metap = (HashMetaPage) pg;
252 metap->hashm_magic = HASH_MAGIC;
253 metap->hashm_version = HASH_VERSION;
254 metap->hashm_ntuples = 0;
255 metap->hashm_nmaps = 0;
256 metap->hashm_ffactor = ffactor;
257 metap->hashm_bsize = BufferGetPageSize(metabuf);
258 /* find largest bitmap array size that will fit in page size */
259 for (i = _hash_log2(metap->hashm_bsize); i > 0; --i)
261 if ((1 << i) <= (metap->hashm_bsize -
262 (MAXALIGN(sizeof(PageHeaderData)) +
263 MAXALIGN(sizeof(HashPageOpaqueData)))))
267 metap->hashm_bmsize = 1 << i;
268 metap->hashm_bmshift = i + BYTE_TO_BIT;
269 Assert((1 << BMPG_SHIFT(metap)) == (BMPG_MASK(metap) + 1));
271 metap->hashm_procid = index_getprocid(rel, 1, HASHPROC);
274 * We initialize the index with two buckets, 0 and 1, occupying physical
275 * blocks 1 and 2. The first freespace bitmap page is in block 3.
277 metap->hashm_maxbucket = metap->hashm_lowmask = 1; /* nbuckets - 1 */
278 metap->hashm_highmask = 3; /* (nbuckets << 1) - 1 */
280 MemSet(metap->hashm_spares, 0, sizeof(metap->hashm_spares));
281 MemSet(metap->hashm_mapp, 0, sizeof(metap->hashm_mapp));
283 metap->hashm_spares[1] = 1; /* the first bitmap page is only spare */
284 metap->hashm_ovflpoint = 1;
285 metap->hashm_firstfree = 0;
288 * Initialize the first two buckets
290 for (i = 0; i <= 1; i++)
292 buf = _hash_getbuf(rel, BUCKET_TO_BLKNO(metap, i), HASH_WRITE);
293 pg = BufferGetPage(buf);
294 _hash_pageinit(pg, BufferGetPageSize(buf));
295 pageopaque = (HashPageOpaque) PageGetSpecialPointer(pg);
296 pageopaque->hasho_prevblkno = InvalidBlockNumber;
297 pageopaque->hasho_nextblkno = InvalidBlockNumber;
298 pageopaque->hasho_bucket = i;
299 pageopaque->hasho_flag = LH_BUCKET_PAGE;
300 pageopaque->hasho_filler = HASHO_FILL;
301 _hash_wrtbuf(rel, buf);
305 * Initialize first bitmap page. Can't do this until we create the first
306 * two buckets, else smgr will complain.
308 _hash_initbitmap(rel, metap, 3);
311 _hash_wrtbuf(rel, metabuf);
315 * _hash_pageinit() -- Initialize a new hash index page.
318 _hash_pageinit(Page page, Size size)
320 Assert(PageIsNew(page));
321 PageInit(page, size, sizeof(HashPageOpaqueData));
325 * Attempt to expand the hash table by creating one new bucket.
327 * This will silently do nothing if it cannot get the needed locks.
329 * The caller should hold no locks on the hash index.
331 * The caller must hold a pin, but no lock, on the metapage buffer.
332 * The buffer is returned in the same state.
335 _hash_expandtable(Relation rel, Buffer metabuf)
341 BlockNumber start_oblkno;
342 BlockNumber start_nblkno;
348 * Obtain the page-zero lock to assert the right to begin a split (see
351 * Note: deadlock should be impossible here. Our own backend could only be
352 * holding bucket sharelocks due to stopped indexscans; those will not
353 * block other holders of the page-zero lock, who are only interested in
354 * acquiring bucket sharelocks themselves. Exclusive bucket locks are
355 * only taken here and in hashbulkdelete, and neither of these operations
356 * needs any additional locks to complete. (If, due to some flaw in this
357 * reasoning, we manage to deadlock anyway, it's okay to error out; the
358 * index will be left in a consistent state.)
360 _hash_getlock(rel, 0, HASH_EXCLUSIVE);
362 /* Write-lock the meta page */
363 _hash_chgbufaccess(rel, metabuf, HASH_NOLOCK, HASH_WRITE);
365 _hash_checkpage(rel, metabuf, LH_META_PAGE);
366 metap = (HashMetaPage) BufferGetPage(metabuf);
369 * Check to see if split is still needed; someone else might have already
370 * done one while we waited for the lock.
372 * Make sure this stays in sync with _hash_doinsert()
374 if (metap->hashm_ntuples <=
375 (double) metap->hashm_ffactor * (metap->hashm_maxbucket + 1))
379 * Determine which bucket is to be split, and attempt to lock the old
380 * bucket. If we can't get the lock, give up.
382 * The lock protects us against other backends, but not against our own
383 * backend. Must check for active scans separately.
385 * Ideally we would lock the new bucket too before proceeding, but if we
386 * are about to cross a splitpoint then the BUCKET_TO_BLKNO mapping isn't
387 * correct yet. For simplicity we update the metapage first and then
388 * lock. This should be okay because no one else should be trying to lock
389 * the new bucket yet...
391 new_bucket = metap->hashm_maxbucket + 1;
392 old_bucket = (new_bucket & metap->hashm_lowmask);
394 start_oblkno = BUCKET_TO_BLKNO(metap, old_bucket);
396 if (_hash_has_active_scan(rel, old_bucket))
399 if (!_hash_try_getlock(rel, start_oblkno, HASH_EXCLUSIVE))
403 * Okay to proceed with split. Update the metapage bucket mapping info.
405 * Since we are scribbling on the metapage data right in the shared
406 * buffer, any failure in this next little bit leaves us with a big
407 * problem: the metapage is effectively corrupt but could get written back
408 * to disk. We don't really expect any failure, but just to be sure,
409 * establish a critical section.
411 START_CRIT_SECTION();
413 metap->hashm_maxbucket = new_bucket;
415 if (new_bucket > metap->hashm_highmask)
417 /* Starting a new doubling */
418 metap->hashm_lowmask = metap->hashm_highmask;
419 metap->hashm_highmask = new_bucket | metap->hashm_lowmask;
423 * If the split point is increasing (hashm_maxbucket's log base 2
424 * increases), we need to adjust the hashm_spares[] array and
425 * hashm_ovflpoint so that future overflow pages will be created beyond
426 * this new batch of bucket pages.
428 * XXX should initialize new bucket pages to prevent out-of-order page
429 * creation? Don't wanna do it right here though.
431 spare_ndx = _hash_log2(metap->hashm_maxbucket + 1);
432 if (spare_ndx > metap->hashm_ovflpoint)
434 Assert(spare_ndx == metap->hashm_ovflpoint + 1);
435 metap->hashm_spares[spare_ndx] = metap->hashm_spares[metap->hashm_ovflpoint];
436 metap->hashm_ovflpoint = spare_ndx;
439 /* now we can compute the new bucket's primary block number */
440 start_nblkno = BUCKET_TO_BLKNO(metap, new_bucket);
442 Assert(!_hash_has_active_scan(rel, new_bucket));
444 if (!_hash_try_getlock(rel, start_nblkno, HASH_EXCLUSIVE))
445 elog(PANIC, "could not get lock on supposedly new bucket");
447 /* Done mucking with metapage */
451 * Copy bucket mapping info now; this saves re-accessing the meta page
452 * inside _hash_splitbucket's inner loop. Note that once we drop the
453 * split lock, other splits could begin, so these values might be out of
454 * date before _hash_splitbucket finishes. That's okay, since all it
455 * needs is to tell which of these two buckets to map hashkeys into.
457 maxbucket = metap->hashm_maxbucket;
458 highmask = metap->hashm_highmask;
459 lowmask = metap->hashm_lowmask;
461 /* Write out the metapage and drop lock, but keep pin */
462 _hash_chgbufaccess(rel, metabuf, HASH_WRITE, HASH_NOLOCK);
464 /* Release split lock; okay for other splits to occur now */
465 _hash_droplock(rel, 0, HASH_EXCLUSIVE);
467 /* Relocate records to the new bucket */
468 _hash_splitbucket(rel, metabuf, old_bucket, new_bucket,
469 start_oblkno, start_nblkno,
470 maxbucket, highmask, lowmask);
472 /* Release bucket locks, allowing others to access them */
473 _hash_droplock(rel, start_oblkno, HASH_EXCLUSIVE);
474 _hash_droplock(rel, start_nblkno, HASH_EXCLUSIVE);
478 /* Here if decide not to split or fail to acquire old bucket lock */
481 /* We didn't write the metapage, so just drop lock */
482 _hash_chgbufaccess(rel, metabuf, HASH_READ, HASH_NOLOCK);
484 /* Release split lock */
485 _hash_droplock(rel, 0, HASH_EXCLUSIVE);
490 * _hash_splitbucket -- split 'obucket' into 'obucket' and 'nbucket'
492 * We are splitting a bucket that consists of a base bucket page and zero
493 * or more overflow (bucket chain) pages. We must relocate tuples that
494 * belong in the new bucket, and compress out any free space in the old
497 * The caller must hold exclusive locks on both buckets to ensure that
498 * no one else is trying to access them (see README).
500 * The caller must hold a pin, but no lock, on the metapage buffer.
501 * The buffer is returned in the same state. (The metapage is only
502 * touched if it becomes necessary to add or remove overflow pages.)
505 _hash_splitbucket(Relation rel,
509 BlockNumber start_oblkno,
510 BlockNumber start_nblkno,
522 HashPageOpaque oopaque;
523 HashPageOpaque nopaque;
526 OffsetNumber ooffnum;
527 OffsetNumber noffnum;
528 OffsetNumber omaxoffnum;
531 TupleDesc itupdesc = RelationGetDescr(rel);
534 * It should be okay to simultaneously write-lock pages from each bucket,
535 * since no one else can be trying to acquire buffer lock on pages of
538 oblkno = start_oblkno;
539 obuf = _hash_getbuf(rel, oblkno, HASH_WRITE);
540 _hash_checkpage(rel, obuf, LH_BUCKET_PAGE);
541 opage = BufferGetPage(obuf);
542 oopaque = (HashPageOpaque) PageGetSpecialPointer(opage);
544 nblkno = start_nblkno;
545 nbuf = _hash_getbuf(rel, nblkno, HASH_WRITE);
546 npage = BufferGetPage(nbuf);
548 /* initialize the new bucket's primary page */
549 _hash_pageinit(npage, BufferGetPageSize(nbuf));
550 nopaque = (HashPageOpaque) PageGetSpecialPointer(npage);
551 nopaque->hasho_prevblkno = InvalidBlockNumber;
552 nopaque->hasho_nextblkno = InvalidBlockNumber;
553 nopaque->hasho_bucket = nbucket;
554 nopaque->hasho_flag = LH_BUCKET_PAGE;
555 nopaque->hasho_filler = HASHO_FILL;
558 * Partition the tuples in the old bucket between the old bucket and the
559 * new bucket, advancing along the old bucket's overflow bucket chain and
560 * adding overflow pages to the new bucket as needed.
562 ooffnum = FirstOffsetNumber;
563 omaxoffnum = PageGetMaxOffsetNumber(opage);
567 * at each iteration through this loop, each of these variables should
568 * be up-to-date: obuf opage oopaque ooffnum omaxoffnum
571 /* check if we're at the end of the page */
572 if (ooffnum > omaxoffnum)
574 /* at end of page, but check for an(other) overflow page */
575 oblkno = oopaque->hasho_nextblkno;
576 if (!BlockNumberIsValid(oblkno))
580 * we ran out of tuples on this particular page, but we have more
581 * overflow pages; advance to next page.
583 _hash_wrtbuf(rel, obuf);
585 obuf = _hash_getbuf(rel, oblkno, HASH_WRITE);
586 _hash_checkpage(rel, obuf, LH_OVERFLOW_PAGE);
587 opage = BufferGetPage(obuf);
588 oopaque = (HashPageOpaque) PageGetSpecialPointer(opage);
589 ooffnum = FirstOffsetNumber;
590 omaxoffnum = PageGetMaxOffsetNumber(opage);
595 * Re-hash the tuple to determine which bucket it now belongs in.
597 * It is annoying to call the hash function while holding locks, but
598 * releasing and relocking the page for each tuple is unappealing too.
600 itup = (IndexTuple) PageGetItem(opage, PageGetItemId(opage, ooffnum));
601 datum = index_getattr(itup, 1, itupdesc, &null);
604 bucket = _hash_hashkey2bucket(_hash_datum2hashkey(rel, datum),
605 maxbucket, highmask, lowmask);
607 if (bucket == nbucket)
610 * insert the tuple into the new bucket. if it doesn't fit on the
611 * current page in the new bucket, we must allocate a new overflow
612 * page and place the tuple on that page instead.
614 itemsz = IndexTupleDSize(*itup);
615 itemsz = MAXALIGN(itemsz);
617 if (PageGetFreeSpace(npage) < itemsz)
619 /* write out nbuf and drop lock, but keep pin */
620 _hash_chgbufaccess(rel, nbuf, HASH_WRITE, HASH_NOLOCK);
621 /* chain to a new overflow page */
622 nbuf = _hash_addovflpage(rel, metabuf, nbuf);
623 _hash_checkpage(rel, nbuf, LH_OVERFLOW_PAGE);
624 npage = BufferGetPage(nbuf);
625 /* we don't need nopaque within the loop */
628 noffnum = OffsetNumberNext(PageGetMaxOffsetNumber(npage));
629 if (PageAddItem(npage, (Item) itup, itemsz, noffnum, LP_USED)
630 == InvalidOffsetNumber)
631 elog(ERROR, "failed to add index item to \"%s\"",
632 RelationGetRelationName(rel));
635 * now delete the tuple from the old bucket. after this section
636 * of code, 'ooffnum' will actually point to the ItemId to which
637 * we would point if we had advanced it before the deletion
638 * (PageIndexTupleDelete repacks the ItemId array). this also
639 * means that 'omaxoffnum' is exactly one less than it used to be,
640 * so we really can just decrement it instead of calling
641 * PageGetMaxOffsetNumber.
643 PageIndexTupleDelete(opage, ooffnum);
644 omaxoffnum = OffsetNumberPrev(omaxoffnum);
649 * the tuple stays on this page. we didn't move anything, so we
650 * didn't delete anything and therefore we don't have to change
653 Assert(bucket == obucket);
654 ooffnum = OffsetNumberNext(ooffnum);
659 * We're at the end of the old bucket chain, so we're done partitioning
660 * the tuples. Before quitting, call _hash_squeezebucket to ensure the
661 * tuples remaining in the old bucket (including the overflow pages) are
662 * packed as tightly as possible. The new bucket is already tight.
664 _hash_wrtbuf(rel, obuf);
665 _hash_wrtbuf(rel, nbuf);
667 _hash_squeezebucket(rel, obucket, start_oblkno);