xHarbour Reference Documentation > Function Reference

HSetPartition()

Partitions a linear hash for improved performance.

Syntax

HSetPartition( <hHash>, <nPageSize>, [<nLevel>] ) --> NIL

Arguments

<hHash>

A variable referencing the hash who is partitioned.

<nPageSize>

A numeric value specifying the page size of one hash partition.

<nLevel>

A numeric value indicating how many levels deep the hash should be partitioned.

Return

The function returns always NIL.

Description

The function partitions a linear hash into <nPageSize> numbers of items. By partitioning a linear hash, searching and inserting keys is improved. This is advantageous for hashes of more than 1000 key/value pairs. Smaller hashes do not need to be partitioned, unless they are accessed with a high frequency.

The partitioning of a hash results in a hash of hashes. Keys of a hash are distributed equally in sub-hashes so that searching or inserting a key becomes faster in a partitioned hash compared to a linear hash.

Important:  this function may only be called on empty hashes. Do not pass a populated hash to it. To partition a filled hash, or repartition it, create an empty hash, set the desired partition scheme and merge the filled hash into the partitioned empty hash using HMerge().

Info

See also:	Hash(), HGetPartition(), HMerge()
Category:	Hash functions , xHarbour extensions
Source:	vm\hash.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example employs a small test program that demonstrates
// the effect of partitioning a large hash. The key creation
// is done in a "worst case" scenario, where the key with highest
// sorting order is inserted first into the hash. The key with
// lowest sorting order is inserted last. You can vary the
// #define constants for the number of hash keys, page size
// and partition depth to see how each factor influences
// the entire performance of populating a large hash.

    #define HASH_KEYS   10000
    #define PAGE_SIZE      16   // 20 | 30 | 50
    #define PART_LEVEL      2   //  5 |  4 |  3

    PROCEDURE Main
       LOCAL hHash, cKey, nSize, nLevel
       LOCAL t1, t2, t3

       t1 := Seconds()

       // creating linear hash
       hHash := {=>}
       FOR i:=1 TO HASH_KEYS
          cKey :=  "K" + Padl( HASH_KEYS - i, 6, "0" )
          hHash[ cKey ] := 2 * i
       NEXT

       t2 := Seconds()

       // hash partitioned down to partitioning level
       hHash := {=>}
       HSetPartition( hHash, PAGE_SIZE, PART_LEVEL )

       FOR i:=1 TO HASH_KEYS
          cKey :=  "K" + Padl( HASH_KEYS - i, 6, "0" )
          hHash[ cKey ] := 2 * i
       NEXT

       t3 := Seconds()

       ? "Hash keys  :", Len( hHash )
       ? "linear hash:", 100*(t2-t1)/(t2-t1), "%"   // 100.00 %
       ? "partitioned:", 100*(t3-t2)/(t2-t1), "%"   //   1.80 %
       ? "IsPartition:", HGetPartition( hHash, @nSize, @nLevel )
       ? "Page size  :", nSize
       ? "Level      :", nLevel
    RETURN