h3geodist

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 11, 2022 License: MIT Imports: 9 Imported by: 0

README

H3-geo distributed cells

Documentation Coverage Status Go Report Card

Distribution of Uber H3geo cells by nodes

Prerequisites

H3-Go requires CGO

Install

With a correctly configured Go env:

go get github.com/mmadfox/go-h3geo-dist

Examples

package main

import (
	"fmt"

	h3geodist "github.com/mmadfox/go-h3geo-dist"
	"github.com/uber/h3-go/v3"
)

func main() {
	level := h3geodist.Level1
	h3dist, err := h3geodist.New(level)
	if err != nil {
		panic(err)
	}

	_ = h3dist.Add("127.0.0.1")
	_ = h3dist.Add("127.0.0.2")
	_ = h3dist.Add("127.0.0.3")

	// iterate over all cells level one
	h3geodist.Iter(level, func(index uint, cell h3.H3Index) {
		// find a node by h3geo cell
		dcell, ok := h3dist.Lookup(cell)
		fmt.Printf("h3dist.Lookup: cell=%v, host=%s, found=%v\n", cell, dcell.Host, ok)
	})

	h3dist.LookupMany([]h3.H3Index{
		h3.FromString("821fa7fffffffff"),
		h3.FromString("821f9ffffffffff"),
		h3.FromString("81973ffffffffff"),
		h3.FromString("81f07ffffffffff"),
	}, func(c h3geodist.Cell) bool {
		fmt.Printf("h3dist.LookupMany: cell=%v, host=%s\n", c.H3ID, c.Host)
		return true
	})

	h3dist.Remove("127.0.0.1")
	h3dist.Remove("127.0.0.2")
	h3dist.Remove("127.0.0.3")
}

Documentation

Index

Constants

View Source 
const (
	Level0 = iota // number of unique indexes 122
	Level1        // number of unique indexes 842
	Level2        // number of unique indexes 5882
	Level3        // number of unique indexes 41162
	Level4        // number of unique indexes 288122
	Level5        // number of unique indexes 2016842
	Level6        // number of unique indexes 14117882
)

Supported H3 resolutions.

View Source 
const (
	DefaultReplicationFactor = 9
	DefaultLoadFactor        = 1.25
	DefaultVNodes            = 64
)

Variables

View Source 
var (
	// ErrNoSlots means that the number of virtual nodes is distributed by 100%.
	// It is necessary to change the configuration of virtual nodes.
	ErrNoSlots = errors.New("h3geodist: no distribute slots")

	// ErrVNodes returns when there are no virtual nodes.
	ErrVNodes = errors.New("h3geodist: vnodes not found")
)

Functions

func Iter 

func Iter(level int, fn func(index uint, cell h3.H3Index))

Iter iterate each cell at specified level, calling fn for each cell. Allowed levels 0-6.

func Level0Area 

func Level0Area() uint

Level0Area returns the area (km2) for level 0.

func Level1Area 

func Level1Area() uint

Level1Area returns the area (km2) for level 1.

func Level2Area 

func Level2Area() uint

Level2Area returns the area (km2) for level 2.

func Level3Area 

func Level3Area() uint

Level3Area returns the area (km2) for level 3.

func Level4Area 

func Level4Area() uint

Level4Area returns the area (km2) for level 4.

func Level5Area 

func Level5Area() uint

Level5Area returns the area (km2) for level 5.

func Level6Area 

func Level6Area() uint

Level6Area returns the area (km2) for level 6.

func ToHash added in v0.3.0 

func ToHash(val uint64) uint64

ToHash returns the fvn.Hash64 hash sum from uint64 value.

Types

type Cell 

type Cell struct {
	H3ID h3.H3Index
	Host string
}

Cell is a type to represent a distributed cell with specifying the hostname and H3 Index.

func (Cell) HexID added in v0.2.0 

func (c Cell) HexID() string

func (Cell) String added in v0.2.0 

func (c Cell) String() string

type Distributed 

type Distributed struct {
	// contains filtered or unexported fields
}

Distributed holds information about nodes, and scheduler of virtual nodes with replicas. Thread-safe.

func Default 

func Default() *Distributed

Default creates and returns a new Distributed instance with level - Level5.

func New 

func New(cellLevel int, opts ...Option) (*Distributed, error)

New creates and returns a new Distributed instance with specified cell level and options.

func (*Distributed) Add 

func (d *Distributed) Add(addr string) error

Add adds a new node.

func (*Distributed) Addr added in v0.4.0 

func (d *Distributed) Addr(vnode uint64) (addr string, ok bool)

Addr returns the addr of the node by vnode id.

func (*Distributed) AvgLoad 

func (d *Distributed) AvgLoad() float64

AvgLoad returns the average load.

func (*Distributed) EachCell 

func (d *Distributed) EachCell(iter func(c Cell))

EachCell iterate each distributed cell, calling fn for each cell.

func (*Distributed) EachVNode added in v0.4.0 

func (d *Distributed) EachVNode(fn func(vnode uint64, addr string) bool)

EachVNode iterate each vnode, calling fn for each vnode.

func (*Distributed) IsEmpty 

func (d *Distributed) IsEmpty() bool

IsEmpty returns TRUE if the nodes list are empty, otherwise FALSE.

func (*Distributed) IsOwned 

func (d *Distributed) IsOwned(c Cell) bool

IsOwned сhecks if the host for a distributed cell has changed.

func (*Distributed) Lookup 

func (d *Distributed) Lookup(cell h3.H3Index) (Cell, bool)

Lookup returns distributed cell.

func (*Distributed) LookupFromLatLon 

func (d *Distributed) LookupFromLatLon(lat float64, lon float64) (c Cell, err error)

LookupFromLatLon returns distributed cell.

func (*Distributed) LookupMany 

func (d *Distributed) LookupMany(cell []h3.H3Index, iter func(c Cell) bool) bool

LookupMany returns a list of distributed cell.

func (*Distributed) NeighborsFromLatLon added in v0.2.0 

func (d *Distributed) NeighborsFromLatLon(lat float64, lon float64) (target Cell, neighbors []Neighbor, err error)

NeighborsFromLatLon returns the current distributed cell for a geographic coordinate and neighbors sorted by distance in descending order. Distance is measured from geographic coordinates to the center of each neighbor.

func (*Distributed) Nodes 

func (d *Distributed) Nodes() []string

Nodes returns a list of nodes.

func (*Distributed) NumReplica 

func (d *Distributed) NumReplica() int

NumReplica returns number of replicas.

func (*Distributed) Remove 

func (d *Distributed) Remove(addr string)

Remove removes a node.

func (*Distributed) ReplicaFor 

func (d *Distributed) ReplicaFor(cell h3.H3Index, n int) ([]string, error)

ReplicaFor returns a list of hosts for replication.

func (*Distributed) Stats 

func (d *Distributed) Stats() []NodeInfo

Stats returns load distribution by nodes.

func (*Distributed) VNodeIndex 

func (d *Distributed) VNodeIndex(cell h3.H3Index) int

VNodeIndex returns the Index of the virtual node by H3Index.

func (*Distributed) VNodes 

func (d *Distributed) VNodes() uint64

VNodes returns number of virtual nodes.

func (*Distributed) WhereIsMyParent 

func (d *Distributed) WhereIsMyParent(child h3.H3Index) (c Cell, err error)

WhereIsMyParent finds and returns parent distributed cell. The child object must be less resolution than the parent's parent.

type Neighbor added in v0.2.0 

type Neighbor struct {
	Cell      Cell
	DistanceM float64
}

Neighbor is a type for represent a neighbor distributed cell, with the distance from a target point to the center of each neighbor.

type NodeInfo 

type NodeInfo struct {
	Host string
	Load float64
}

NodeInfo is a type to represent a node load statistic.

type Option 

type Option func(*Distributed)

Option is a type to represent various Distributed options.

func WithLoadFactor 

func WithLoadFactor(val float64) Option

WithLoadFactor sets the number of load factor. Default 1.25.

func WithReplicationFactor 

func WithReplicationFactor(val int) Option

WithReplicationFactor sets the number of replication factor. Default 9. A value less than or equal to 0 is set to 1.

func WithVNodes 

func WithVNodes(val uint64) Option

WithVNodes sets the number of virtual nodes. Default 64.

Source Files

View all Source files

Directories

Path Synopsis
examples
dist
neighbors
owned
relocation
sample

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.