hazelcast

package module
Version: v1.0.0-preview.1 Latest Latest
Warning

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

Go to latest
Published: May 7, 2021 License: Apache-2.0 Imports: 31 Imported by: 137

README


Note to Hazelcast Go Client for Hazelcast 3 Users

Support for Hazelcast 3.x ended on April 9th 2021, so Go client for Hazelcast 3 will not be updated. You can still use Go client for Hazelcast 3 by migrating your project to use Go modules and adding the following in your go.mod file:

require github.com/hazelcast/hazelcast-go-client v0.6.0

Note

The master branch is the development branch for the upcoming version 1 of the client. Version 1 is currently in alpha stage:

  • CODE IN THIS BRANCH IS IN NO WAY SUPPORTED FOR ANY PRODUCTION USE.
  • API IN THIS BRANCH CAN CHANGE IN BREAKING WAYS AT ANY TIME.

Your feedback and contribution are appreciated! Join us at Hazelcast Community Slack


Hazelcast Go Client

Hazelcast is an open-source distributed in-memory data store and computation platform that provides a wide variety of distributed data structures and concurrency primitives.

Hazelcast Go client is a way to communicate to Hazelcast IMDG clusters and access the cluster data.

Release Notes

1.0.0 Preview 1 (2021-05-07)

The first preview release of the Hazelcast Go client has the following features:

Expect breaking changes in the following areas:

  • Configuration.
  • Map lock functions.

Sample Code

package main

import (
	"fmt"
	"log"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	// create the client and connect to the cluster
	client, err := hazelcast.StartNewClient() 
    if err != nil {
    	log.Fatal(err)
    }
    // get a map
    people, err := client.GetMap("people")
    if err != nil {
        log.Fatal(err)
    }
    personName := "Jane Doe"
    // set a value in the map
    if err = people.Set(personName, 30); err != nil {
    	log.Fatal(err)
    }
    // get a value from the map
    age, err := people.Get(personName)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s is %d years old.\n", personName, age)
}

Features

  • Distributed, partitioned and queryable in-memory key-value store implementation, called Map.
  • Additional data structures and simple messaging constructs such as Replicated Map, Queue and Topic.
  • Support for serverless and traditional web service architectures with Unisocket and Smart operation modes.
  • Ability to listen to client lifecycle, cluster state, and distributed data structure events.

Install

Requirements:

  • Hazelcast Go client is compatible only with Hazelcast IMDG 4.x and above.

In your Go module enabled project, add a dependency to github.com/hazelcast/hazelcast-go-client:

# Depend on the latest version
$ go get github.com/hazelcast/hazelcast-go-client

# Depend on a specific release
$ go get github.com/hazelcast/hazelcast-go-client@v1.0.0-preview.1

Quick Start

Hazelcast Go client requires a working Hazelcast IMDG cluster. This cluster handles the storage and manipulation of the user data.

A Hazelcast IMDG cluster consists of one or more cluster members. These members generally run on multiple virtual or physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to multiple members transparent to the user. It is therefore very easy to scale the system by adding new members as the data grows. Hazelcast IMDG cluster also offers resilience. Should any hardware or software problem causes a crash to any member, the data on that member is recovered from backups and the cluster continues to operate without any downtime.

The quickest way to start a single member cluster for development purposes is to use our Docker images.

docker run --rm --name hazelcast -p 5701:5701 hazelcast/hazelcast:4.2

You can also use our ZIP or TAR distributions. After the download, you can start the Hazelcast member using the bin/start.sh script.

Starting the Default Client

Start the client with the default Hazelcast IMDG host and port using hazelcast.StartNewClient:

client, err := hazelcast.StartNewClient()
// handle client start error

Starting the Client with Given Options

Note that ClientConfigBuilder is not thread-safe. Complete creating the configuration in a single go routine, do not pass configuration builder to other go routines without synchronization.

// create the config builder
cb := hazelcast.NewConfigBuilder()

// optionally turn off smart routing
cb.Cluster().SetSmartRouting(false).
    // optionally set cluster addresses manually
    SetAddrs("member1.example.com", "member2.example.com")

// create and start the client with the configuration provider
client, err := hazelcast.StartNewClientWithConfig(cb)
// handle client start error

Documentation

Use godoc:

$ godoc -http=localhost:5500

godoc is not installed by default with the base Go distribution. Install it using:

$ go get -u golang.org/x/tools/...`

Support

Join us at Go Client channel or Hazelcast at Google Groups.

Running the tests

Currently we support only Linux and MacOS for testing the client.

You need to have the following installed in order to run integration tests:

  • Java 8
  • Maven 3 or better
  • Bash
  • Make

Before running the tests, starts Hazelcast Remote Controller, which enables the test suite to create clusters:

# Start RC with Hazelcast Community features
$ ./start-rc.sh

# Or, start RC with Hazelcast Enterprise features
$ HAZELCAST_ENTERPRISE_KEY=ENTERPRISE-KEY-HERE ./start-rc.sh 

You can run the tests using one of the following approaches:

  • Run make test-all to run integration tests.
  • Run make test-all-race to run integration tests with race detection.
  • Run make test-cover to generate the coverage report and make view-cover to view the test coverage summary and generate an HTML report.

Testing the client with SSL support requires running the remote controller with Hazelcast Enterprise features. To enable SSL connections, add ENABLE_SSL=1 to environment variables, or prepend it to the make commands above.

In order to turn on verbose logging, add ENABLE_TRACE=1 to environment variables, or prepend it to the make commands above.

License

Apache 2 License.

Copyright (c) 2008-2021, Hazelcast, Inc. All Rights Reserved.

Visit www.hazelcast.com for more information.

Documentation

Overview

Package hazelcast provides the Hazelcast Go client.

Example
// Create a configuration builder.
configBuilder := hazelcast.NewConfigBuilder()
configBuilder.Cluster().
	SetName("my-cluster").
	SetAddrs("192.168.1.42:5000", "192.168.1.42:5001")
// Start the client with the configuration provider.
client, err := hazelcast.StartNewClientWithConfig(configBuilder)
if err != nil {
	log.Fatal(err)
}
// Retrieve a map.
peopleMap, err := client.GetMap("people")
if err != nil {
	log.Fatal(err)
}
// Call map functions.
err = peopleMap.Set("jane", "doe")
if err != nil {
	log.Fatal(err)
}
// Stop the client once you are done with it.
client.Shutdown()
Output:

Index

Examples

Constants

View Source
const (
	// NotifyEntryAdded is dispatched if an entry is added.
	NotifyEntryAdded = int32(1 << 0)
	// NotifyEntryRemoved is dispatched if an entry is removed.
	NotifyEntryRemoved = int32(1 << 1)
	// NotifyEntryUpdated is dispatched if an entry is updated.
	NotifyEntryUpdated = int32(1 << 2)
	// NotifyEntryEvicted is dispatched if an entry is evicted.
	NotifyEntryEvicted = int32(1 << 3)
	// NotifyEntryExpired is dispatched if an entry is expired.
	NotifyEntryExpired = int32(1 << 4)
	// NotifyEntryAllEvicted is dispatched if all entries are evicted.
	NotifyEntryAllEvicted = int32(1 << 5)
	// NotifyEntryAllCleared is dispatched if all entries are cleared.
	NotifyEntryAllCleared = int32(1 << 6)
	// NotifyEntryMerged is dispatched if an entry is merged after a network partition.
	NotifyEntryMerged = int32(1 << 7)
	// NotifyEntryInvalidated is dispatched if an entry is invalidated.
	NotifyEntryInvalidated = int32(1 << 8)
	// NotifyEntryLoaded is dispatched if an entry is loaded.
	NotifyEntryLoaded = int32(1 << 9)
)
View Source
const (
	NotifyItemAdded   int32 = 1
	NotifyItemRemoved int32 = 2
)
View Source
const (
	TtlDefault     = -1
	TtlUnlimited   = 0
	MaxIdleDefault = -1
)

Variables

View Source
var (
	ErrClientCannotStart = errors.New("client cannot start")
	ErrClientNotReady    = errors.New("client not ready")
	ErrContextIsNil      = errors.New("context is nil")
)

Functions

This section is empty.

Types

type Client

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

func StartNewClient added in v1.0.0

func StartNewClient() (*Client, error)

StartNewClient creates and starts a new client. Hazelcast client enables you to do all Hazelcast operations without being a member of the cluster. It connects to one or more of the cluster members and delegates all cluster wide operations to them.

func StartNewClientWithConfig added in v1.0.0

func StartNewClientWithConfig(configProvider ConfigProvider) (*Client, error)

StartNewClientWithConfig creates and starts a new client with the given configuration. Hazelcast client enables you to do all Hazelcast operations without being a member of the cluster. It connects to one or more of the cluster members and delegates all cluster wide operations to them.

func (*Client) AddLifecycleListener added in v1.0.0

func (c *Client) AddLifecycleListener(handler LifecycleStateChangeHandler) (types.UUID, error)

AddLifecycleListener adds a lifecycle state change handler after the client starts. The listener is attached to the client after the client starts, so lifecyle events after the client start can be received. Use the returned subscription ID to remove the listener. The handler must not block.

func (*Client) AddMembershipListener added in v1.0.0

func (c *Client) AddMembershipListener(handler cluster.MembershipStateChangeHandler) (types.UUID, error)

AddMembershipListener adds a member state change handler with a unique subscription ID. The listener is attached to the client after the client starts, so membership events after the client start can be received. Use the returned subscription ID to remove the listener.

func (*Client) GetMap

func (c *Client) GetMap(name string) (*Map, error)

GetMap returns a distributed map instance.

func (*Client) GetQueue

func (c *Client) GetQueue(name string) (*Queue, error)

func (*Client) GetReplicatedMap

func (c *Client) GetReplicatedMap(name string) (*ReplicatedMap, error)

GetReplicatedMap returns a replicated map instance.

func (*Client) GetTopic

func (c *Client) GetTopic(name string) (*Topic, error)

func (*Client) Name

func (c *Client) Name() string

Name returns client's name Use ConfigBuilder.SetName to set the client name. If not set manually, an automatic name is used.

func (*Client) RemoveLifecycleListener added in v1.0.0

func (c *Client) RemoveLifecycleListener(subscriptionID types.UUID) error

RemoveLifecycleListener removes the lifecycle state change handler with the given subscription ID

func (*Client) RemoveMembershipListener added in v1.0.0

func (c *Client) RemoveMembershipListener(subscriptionID types.UUID) error

RemoveMembershipListener removes the member state change handler with the given subscription ID.

func (*Client) Shutdown

func (c *Client) Shutdown() error

Shutdown disconnects the client from the cluster.

type ClusterConfigBuilder

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

func (*ClusterConfigBuilder) SSL

func (*ClusterConfigBuilder) Security

func (*ClusterConfigBuilder) SetAddrs

func (b *ClusterConfigBuilder) SetAddrs(addrs ...string) *ClusterConfigBuilder

SetAddrs sets the candidate address list that client will use to establish initial connection. Other members of the cluster will be discovered when the client starts. By default localhost:5701 is set as the member address.

func (*ClusterConfigBuilder) SetConnectionTimeout

func (b *ClusterConfigBuilder) SetConnectionTimeout(timeout time.Duration) *ClusterConfigBuilder

SetConnectionTimeout is socket timeout value for client to connect member nodes. The default connection timeout is 5 seconds.

func (*ClusterConfigBuilder) SetHeartbeatInterval

func (b *ClusterConfigBuilder) SetHeartbeatInterval(interval time.Duration) *ClusterConfigBuilder

SetHeartbeatInterval sets time interval between the heartbeats sent by the client to the member nodes. The client sends heartbeats to the cluster in order to avoid stale connections. The default heartbeat interval is 5 seconds.

func (*ClusterConfigBuilder) SetHeartbeatTimeout

func (b *ClusterConfigBuilder) SetHeartbeatTimeout(timeout time.Duration) *ClusterConfigBuilder

SetHeartbeatTimeout sets the hearbeat timeout. If no request is sent to the cluster including heartbeats before timeout, the connection is closed.

func (*ClusterConfigBuilder) SetInvocationTimeout

func (b *ClusterConfigBuilder) SetInvocationTimeout(timeout time.Duration) *ClusterConfigBuilder

SetInvocationTimeout sets the invocation timeout When an invocation gets an exception because * Member throws an exception. * Connection between the client and member is closed. * Client’s heartbeat requests are timed out. Time passed since invocation started is compared with this property. If the time is already passed, then the exception is delegated to the user. If not, the invocation is retried. Note that, if invocation gets no exception and it is a long running one, then it will not get any exception, no matter how small this timeout is set. The default invocation timeout is 120 seconds.

func (*ClusterConfigBuilder) SetName

SetName sets the cluster name, The name is sent as part of the the client authentication message and may be verified on the member. The default cluster name is dev.

func (*ClusterConfigBuilder) SetRedoOperation

func (b *ClusterConfigBuilder) SetRedoOperation(enable bool) *ClusterConfigBuilder

func (*ClusterConfigBuilder) SetSmartRouting

func (b *ClusterConfigBuilder) SetSmartRouting(enable bool) *ClusterConfigBuilder

SetSmartRouting enables or disables smart mode for the client. Smart clients send key based operations to owner of the keys. Unisocket clients send all operations to a single node. Smart routing is enabled by default.

type ClusterSSLConfigBuilder

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

func (*ClusterSSLConfigBuilder) AddClientCertAndEncryptedKeyPath

func (b *ClusterSSLConfigBuilder) AddClientCertAndEncryptedKeyPath(certPath string, privateKeyPath string, password string) *ClusterSSLConfigBuilder

AddClientCertAndEncryptedKeyPath decrypts the keyfile with the given password and adds client certificate path and the decrypted client private key to tls config. The files in the given paths must contain PEM encoded data. The key file should have a DEK-info header otherwise an error will be returned. In order to add multiple client certificate-key pairs one should call this function for each of them. If certificates is empty then no certificate will be sent to the server. If this is unacceptable to the server then it may abort the handshake. For mutual authentication at least one client certificate should be added. It returns an error if any of files cannot be loaded.

func (*ClusterSSLConfigBuilder) AddClientCertAndKeyPath

func (b *ClusterSSLConfigBuilder) AddClientCertAndKeyPath(clientCertPath string, clientPrivateKeyPath string) *ClusterSSLConfigBuilder

AddClientCertAndKeyPath adds client certificate path and client private key path to tls config. The files in the given paths must contain PEM encoded data. In order to add multiple client certificate-key pairs one should call this function for each of them. If certificates is empty then no certificate will be sent to the server. If this is unacceptable to the server then it may abort the handshake. For mutual authentication at least one client certificate should be added. It returns an error if any of files cannot be loaded.

func (*ClusterSSLConfigBuilder) ResetTLSConfig

func (b *ClusterSSLConfigBuilder) ResetTLSConfig(tlsConfig *tls.Config) *ClusterSSLConfigBuilder

func (*ClusterSSLConfigBuilder) SetCAPath

SetCAPath sets CA file path.

func (*ClusterSSLConfigBuilder) SetEnabled

func (b *ClusterSSLConfigBuilder) SetEnabled(enabled bool) *ClusterSSLConfigBuilder

type ClusterSecurityConfigBuilder

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

func (*ClusterSecurityConfigBuilder) SetCredentials

func (b *ClusterSecurityConfigBuilder) SetCredentials(username string, password string) *ClusterSecurityConfigBuilder

type Config added in v1.0.0

type Config struct {
	ClientName          string
	ClusterConfig       cluster.Config
	SerializationConfig serialization.Config
	LoggerConfig        logger.Config
	// contains filtered or unexported fields
}

Config contains configuration for a client. Although it is possible to set the values of the configuration directly, prefer to use the ConfigBuilder, since ConfigBuilder correctly sets the defaults.

type ConfigBuilder

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

ConfigBuilder is used to build configuration for a Hazelcast client.

func NewConfigBuilder

func NewConfigBuilder() *ConfigBuilder

NewConfigBuilder creates a new ConfigBuilder.

func (*ConfigBuilder) AddLifecycleListener

func (c *ConfigBuilder) AddLifecycleListener(handler LifecycleStateChangeHandler) types.UUID

AddLifecycleListener adds a lifecycle listener. The listener is attached to the client before the client starts, so all lifecycle events can be received. Use the returned subscription ID to remove the listener. The handler must not block.

func (*ConfigBuilder) AddMembershipListener

func (c *ConfigBuilder) AddMembershipListener(handler cluster.MembershipStateChangeHandler) types.UUID

AddMembershipListener adds a membership listeener. The listener is attached to the client before the client starts, so all membership events can be received. Use the returned subscription ID to remove the listener.

func (*ConfigBuilder) Cluster

func (c *ConfigBuilder) Cluster() *ClusterConfigBuilder

Cluster returns the cluster configuration builder.

func (ConfigBuilder) Config

func (c ConfigBuilder) Config() (*Config, error)

Config completes building the configuration and returns it.

func (*ConfigBuilder) Logger

func (c *ConfigBuilder) Logger() *LoggerConfigBuilder

func (*ConfigBuilder) Serialization

func (c *ConfigBuilder) Serialization() *SerializationConfigBuilder

Serialization returns the serialization configuration builder.

func (*ConfigBuilder) SetClientName

func (c *ConfigBuilder) SetClientName(name string) *ConfigBuilder

SetClientName sets the client name

type ConfigProvider

type ConfigProvider interface {
	Config() (*Config, error)
}

type EntryNotified added in v1.0.0

type EntryNotified struct {
	EventType               int32
	MapName                 string
	Member                  cluster.Member
	Key                     interface{}
	Value                   interface{}
	OldValue                interface{}
	MergingValue            interface{}
	NumberOfAffectedEntries int
}

func (*EntryNotified) EventName added in v1.0.0

func (e *EntryNotified) EventName() string

type EntryNotifiedHandler added in v1.0.0

type EntryNotifiedHandler func(event *EntryNotified)

type LifecycleState added in v1.0.0

type LifecycleState int
const (
	// LifecycleStateStarting signals that the client is starting.
	LifecycleStateStarting LifecycleState = iota
	// LifecycleStateStarted signals that the client started.
	LifecycleStateStarted
	// LifecycleStateShuttingDown signals that the client is shutting down.
	LifecycleStateShuttingDown
	// LifecycleStateShutDown signals that the client shut down.
	LifecycleStateShutDown
	// LifecycleStateClientConnected signals that the client connected to the cluster.
	LifecycleStateClientConnected
	// LifecycleStateClientDisconnected signals that the client disconnected from the cluster.
	LifecycleStateClientDisconnected
)

type LifecycleStateChangeHandler added in v1.0.0

type LifecycleStateChangeHandler func(event LifecycleStateChanged)

type LifecycleStateChanged added in v1.0.0

type LifecycleStateChanged struct {
	State LifecycleState
}

func (*LifecycleStateChanged) EventName added in v1.0.0

func (e *LifecycleStateChanged) EventName() string

type LoggerConfigBuilder

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

func (*LoggerConfigBuilder) SetLevel

type Map added in v1.0.0

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

func (*Map) AddEntryListener added in v1.0.0

func (m *Map) AddEntryListener(config MapEntryListenerConfig, handler EntryNotifiedHandler) (types.UUID, error)

AddEntryListener adds a continuous entry listener to this map.

func (*Map) AddIndexWithConfig

func (m *Map) AddIndexWithConfig(indexConfig types.IndexConfig) error

AddIndexWithConfig adds an index to this map for the specified entries so that queries can run faster.

func (*Map) AddInterceptor added in v1.0.0

func (m *Map) AddInterceptor(interceptor interface{}) (string, error)

AddInterceptor adds an interceptor for this map.

func (*Map) Clear added in v1.0.0

func (m *Map) Clear() error

Clear deletes all entries one by one and fires related events

func (*Map) ContainsKey added in v1.0.0

func (m *Map) ContainsKey(key interface{}) (bool, error)

ContainsKey returns true if the map contains an entry with the given key

func (*Map) ContainsValue added in v1.0.0

func (m *Map) ContainsValue(value interface{}) (bool, error)

ContainsValue returns true if the map contains an entry with the given value

func (*Map) Delete added in v1.0.0

func (m *Map) Delete(key interface{}) error

Delete removes the mapping for a key from this map if it is present Unlike remove(object), this operation does not return the removed value, which avoids the serialization cost of the returned value. If the removed value will not be used, a delete operation is preferred over a remove operation for better performance.

func (Map) Destroy added in v1.0.0

func (p Map) Destroy() error

func (*Map) Evict added in v1.0.0

func (m *Map) Evict(key interface{}) (bool, error)

Evict evicts the mapping for a key from this map. Returns true if the key is evicted.

func (*Map) EvictAll added in v1.0.0

func (m *Map) EvictAll() error

EvictAll deletes all entries withour firing releated events

func (*Map) ExecuteOnEntries added in v1.0.0

func (m *Map) ExecuteOnEntries(entryProcessor interface{}) ([]types.Entry, error)

ExecuteOnEntries applies the user defined EntryProcessor to all the entries in the map.

func (*Map) Flush added in v1.0.0

func (m *Map) Flush() error

Flush flushes all the local dirty entries.

func (*Map) ForceUnlock added in v1.0.0

func (m *Map) ForceUnlock(key interface{}) error

ForceUnlock releases the lock for the specified key regardless of the lock owner. It always successfully unlocks the key, never blocks, and returns immediately.

func (*Map) Get added in v1.0.0

func (m *Map) Get(key interface{}) (interface{}, error)

Get returns the value for the specified key, or nil if this map does not contain this key. Warning: This method returns a clone of original value, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.

func (*Map) GetAll added in v1.0.0

func (m *Map) GetAll(keys ...interface{}) ([]types.Entry, error)

GetAll returns the entries for the given keys.

func (*Map) GetEntrySet added in v1.0.0

func (m *Map) GetEntrySet() ([]types.Entry, error)

GetEntrySet returns a clone of the mappings contained in this map.

func (*Map) GetEntrySetWithPredicate added in v1.0.0

func (m *Map) GetEntrySetWithPredicate(predicate predicate.Predicate) ([]types.Entry, error)

GetEntrySetWithPredicate returns a clone of the mappings contained in this map.

func (*Map) GetEntryView added in v1.0.0

func (m *Map) GetEntryView(key string) (*types.SimpleEntryView, error)

GetEntryView returns the SimpleEntryView for the specified key.

func (*Map) GetKeySet added in v1.0.0

func (m *Map) GetKeySet() ([]interface{}, error)

GetKeySet returns keys contained in this map

func (*Map) GetKeySetWithPredicate added in v1.0.0

func (m *Map) GetKeySetWithPredicate(predicate predicate.Predicate) ([]interface{}, error)

GetKeySetWithPredicate returns keys contained in this map

func (*Map) GetValues added in v1.0.0

func (m *Map) GetValues() ([]interface{}, error)

GetValues returns a list clone of the values contained in this map

func (*Map) GetValuesWithPredicate added in v1.0.0

func (m *Map) GetValuesWithPredicate(predicate predicate.Predicate) ([]interface{}, error)

GetValuesWithPredicate returns a list clone of the values contained in this map

func (*Map) IsEmpty added in v1.0.0

func (m *Map) IsEmpty() (bool, error)

IsEmpty returns true if this map contains no key-value mappings.

func (*Map) IsLocked added in v1.0.0

func (m *Map) IsLocked(key interface{}) (bool, error)

IsLocked checks the lock for the specified key.

func (*Map) LoadAllReplacing added in v1.0.0

func (m *Map) LoadAllReplacing(keys ...interface{}) error

LoadAllReplacing loads all keys from the store at server side or loads the given keys if provided. Replaces existing keys.

func (*Map) LoadAllWithoutReplacing added in v1.0.0

func (m *Map) LoadAllWithoutReplacing(keys ...interface{}) error

LoadAllWithoutReplacing loads all keys from the store at server side or loads the given keys if provided.

func (*Map) Lock added in v1.0.0

func (m *Map) Lock(key interface{}) error

Lock acquires the lock for the specified key infinitely or for the specified lease time if provided. If the lock is not available, the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

You get a lock whether the value is present in the map or not. Other threads (possibly on other systems) would block on their invoke of lock() until the non-existent key is unlocked. If the lock holder introduces the key to the map, the put() operation is not blocked. If a thread not holding a lock on the non-existent key tries to introduce the key while a lock exists on the non-existent key, the put() operation blocks until it is unlocked.

Scope of the lock is this map only. Acquired lock is only for the key in this map.

Locks are re-entrant; so, if the key is locked N times, it should be unlocked N times before another thread can acquire it.

func (*Map) LockWithLease added in v1.0.0

func (m *Map) LockWithLease(key interface{}, leaseTime time.Duration) error

LockWithLease acquires the lock for the specified key infinitely or for the specified lease time if provided. If the lock is not available, the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

You get a lock whether the value is present in the map or not. Other threads (possibly on other systems) would block on their invoke of lock() until the non-existent key is unlocked. If the lock holder introduces the key to the map, the put() operation is not blocked. If a thread not holding a lock on the non-existent key tries to introduce the key while a lock exists on the non-existent key, the put() operation blocks until it is unlocked.

Scope of the lock is this map only. Acquired lock is only for the key in this map.

Locks are re-entrant; so, if the key is locked N times, it should be unlocked N times before another thread can acquire it. Lease time is the the time to wait before releasing the lock.

func (*Map) Put added in v1.0.0

func (m *Map) Put(key interface{}, value interface{}) (interface{}, error)

Put sets the value for the given key and returns the old value.

func (*Map) PutAll added in v1.0.0

func (m *Map) PutAll(keyValuePairs []types.Entry) error

PutAll copies all of the mappings from the specified map to this map. No atomicity guarantees are given. In the case of a failure, some of the key-value tuples may get written, while others are not.

func (*Map) PutIfAbsent added in v1.0.0

func (m *Map) PutIfAbsent(key interface{}, value interface{}) (interface{}, error)

PutIfAbsent associates the specified key with the given value if it is not already associated.

func (*Map) PutIfAbsentWithTTL added in v1.0.0

func (m *Map) PutIfAbsentWithTTL(key interface{}, value interface{}, ttl time.Duration) (interface{}, error)

PutIfAbsentWithTTL associates the specified key with the given value if it is not already associated. Entry will expire and get evicted after the ttl.

func (*Map) PutIfAbsentWithTTLAndMaxIdle added in v1.0.0

func (m *Map) PutIfAbsentWithTTLAndMaxIdle(key interface{}, value interface{}, ttl time.Duration, maxIdle time.Duration) (interface{}, error)

PutIfAbsentWithTTLAndMaxIdle associates the specified key with the given value if it is not already associated. Entry will expire and get evicted after the ttl. Given max idle time (maximum time for this entry to stay idle in the map) is used.

func (*Map) PutTransient added in v1.0.0

func (m *Map) PutTransient(key interface{}, value interface{}) error

PutTransient sets the value for the given key. MapStore defined at the server side will not be called. The TTL defined on the server-side configuration will be used. Max idle time defined on the server-side configuration will be used.

func (*Map) PutTransientWithMaxIdle added in v1.0.0

func (m *Map) PutTransientWithMaxIdle(key interface{}, value interface{}, maxIdle time.Duration) error

PutTransientWithMaxIdle sets the value for the given key. MapStore defined at the server side will not be called. Given max idle time (maximum time for this entry to stay idle in the map) is used. Set maxIdle to 0 for infinite idle time.

func (*Map) PutTransientWithTTL added in v1.0.0

func (m *Map) PutTransientWithTTL(key interface{}, value interface{}, ttl time.Duration) error

PutTransientWithTTL sets the value for the given key. MapStore defined at the server side will not be called. Given TTL (maximum time in seconds for this entry to stay in the map) is used. Set ttl to 0 for infinite timeout.

func (*Map) PutTransientWithTTLAndMaxIdle added in v1.0.0

func (m *Map) PutTransientWithTTLAndMaxIdle(key interface{}, value interface{}, ttl time.Duration, maxIdle time.Duration) error

PutTransientWithTTLAndMaxIdle sets the value for the given key. MapStore defined at the server side will not be called. Given TTL (maximum time in seconds for this entry to stay in the map) is used. Set ttl to 0 for infinite timeout. Given max idle time (maximum time for this entry to stay idle in the map) is used. Set maxIdle to 0 for infinite idle time.

func (*Map) PutWithMaxIdle added in v1.0.0

func (m *Map) PutWithMaxIdle(key interface{}, value interface{}, maxIdle time.Duration) (interface{}, error)

PutWithMaxIdle sets the value for the given key and returns the old value. maxIdle is the maximum time in seconds for this entry to stay idle in the map.

func (*Map) PutWithTTL added in v1.0.0

func (m *Map) PutWithTTL(key interface{}, value interface{}, ttl time.Duration) (interface{}, error)

PutWithTTL sets the value for the given key and returns the old value. Entry will expire and get evicted after the ttl.

func (*Map) PutWithTTLAndMaxIdle added in v1.0.0

func (m *Map) PutWithTTLAndMaxIdle(key interface{}, value interface{}, ttl time.Duration, maxIdle time.Duration) (interface{}, error)

PutWithTTLAndMaxIdle sets the value for the given key and returns the old value. Entry will expire and get evicted after the ttl. maxIdle is the maximum time in seconds for this entry to stay idle in the map.

func (*Map) Remove added in v1.0.0

func (m *Map) Remove(key interface{}) (interface{}, error)

Remove deletes the value for the given key and returns it.

func (*Map) RemoveAll added in v1.0.0

func (m *Map) RemoveAll(predicate predicate.Predicate) error

RemoveAll deletes all entries matching the given predicate.

func (*Map) RemoveEntryListener added in v1.0.0

func (m *Map) RemoveEntryListener(subscriptionID types.UUID) error

RemoveEntryListener removes the specified entry listener.

func (*Map) RemoveIfSame added in v1.0.0

func (m *Map) RemoveIfSame(key interface{}, value interface{}) (bool, error)

RemoveIfSame removes the entry for a key only if it is currently mapped to a given value. Returns true if the entry was removed.

func (*Map) RemoveInterceptor added in v1.0.0

func (m *Map) RemoveInterceptor(registrationID string) (bool, error)

RemoveInterceptor removes the interceptor.

func (*Map) Replace added in v1.0.0

func (m *Map) Replace(key interface{}, value interface{}) (interface{}, error)

Replace replaces the entry for a key only if it is currently mapped to some value and returns the previous value.

func (*Map) ReplaceIfSame added in v1.0.0

func (m *Map) ReplaceIfSame(key interface{}, oldValue interface{}, newValue interface{}) (bool, error)

ReplaceIfSame replaces the entry for a key only if it is currently mapped to a given value. Returns true if the value was replaced.

func (*Map) Set added in v1.0.0

func (m *Map) Set(key interface{}, value interface{}) error

Set sets the value for the given key.

func (*Map) SetTTL added in v1.0.0

func (m *Map) SetTTL(key interface{}, ttl time.Duration) error

SetTTL updates the TTL value of the entry specified by the given key with a new TTL value. Given TTL (maximum time in seconds for this entry to stay in the map) is used. Set ttl to 0 for infinite timeout.

func (*Map) SetWithTTL added in v1.0.0

func (m *Map) SetWithTTL(key interface{}, value interface{}, ttl time.Duration) error

SetWithTTL sets the value for the given key. Given TTL (maximum time in seconds for this entry to stay in the map) is used. Set ttl to 0 for infinite timeout.

func (*Map) SetWithTTLAndMaxIdle added in v1.0.0

func (m *Map) SetWithTTLAndMaxIdle(key interface{}, value interface{}, ttl time.Duration, maxIdle time.Duration) error

SetWithTTLAndMaxIdle sets the value for the given key. Given TTL (maximum time in seconds for this entry to stay in the map) is used. Set ttl to 0 for infinite timeout. Given max idle time (maximum time for this entry to stay idle in the map) is used. Set maxIdle to 0 for infinite idle time.

func (*Map) Size added in v1.0.0

func (m *Map) Size() (int, error)

Size returns the number of entries in this map.

func (*Map) TryLock added in v1.0.0

func (m *Map) TryLock(key interface{}) (bool, error)

TryLock tries to acquire the lock for the specified key. When the lock is not available, the current thread doesn't wait and returns false immediately.

func (*Map) TryLockWithLease added in v1.0.0

func (m *Map) TryLockWithLease(key interface{}, lease time.Duration) (bool, error)

TryLockWithLease tries to acquire the lock for the specified key. Lock will be released after lease time passes.

func (*Map) TryLockWithLeaseTimeout

func (m *Map) TryLockWithLeaseTimeout(key interface{}, lease time.Duration, timeout time.Duration) (bool, error)

TryLockWithLeaseTimeout tries to acquire the lock for the specified key. The current thread becomes disabled for thread scheduling purposes and lies dormant until one of the followings happens: - The lock is acquired by the current thread, or - The specified waiting time elapses. Lock will be released after lease time passes.

func (*Map) TryLockWithTimeout added in v1.0.0

func (m *Map) TryLockWithTimeout(key interface{}, timeout time.Duration) (bool, error)

TryLockWithTimeout tries to acquire the lock for the specified key. The current thread becomes disabled for thread scheduling purposes and lies dormant until one of the followings happens: - The lock is acquired by the current thread, or - The specified waiting time elapses.

func (*Map) TryPut added in v1.0.0

func (m *Map) TryPut(key interface{}, value interface{}) (bool, error)

TryPut tries to put the given key and value into this map and returns immediately.

func (*Map) TryPutWithTimeout added in v1.0.0

func (m *Map) TryPutWithTimeout(key interface{}, value interface{}, timeout time.Duration) (bool, error)

TryPut tries to put the given key and value into this map and waits until operation is completed or timeout is reached.

func (*Map) TryRemove added in v1.0.0

func (m *Map) TryRemove(key interface{}) (interface{}, error)

TryRemove tries to remove the given key from this map and returns immediately.

func (*Map) TryRemoveWithTimeout added in v1.0.0

func (m *Map) TryRemoveWithTimeout(key interface{}, timeout time.Duration) (interface{}, error)

TryRemoveWithTimeout tries to remove the given key from this map and waits until operation is completed or timeout is reached.

func (*Map) Unlock added in v1.0.0

func (m *Map) Unlock(key interface{}) error

Unlock releases the lock for the specified key.

type MapEntryListenerConfig added in v1.0.0

type MapEntryListenerConfig struct {
	Predicate    predicate.Predicate
	IncludeValue bool
	Key          interface{}
	// contains filtered or unexported fields
}

func (*MapEntryListenerConfig) NotifyEntryAdded added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryAdded(enable bool)

func (*MapEntryListenerConfig) NotifyEntryAllCleared added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryAllCleared(enable bool)

func (*MapEntryListenerConfig) NotifyEntryAllEvicted added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryAllEvicted(enable bool)

func (*MapEntryListenerConfig) NotifyEntryEvicted added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryEvicted(enable bool)

func (*MapEntryListenerConfig) NotifyEntryExpired added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryExpired(enable bool)

func (*MapEntryListenerConfig) NotifyEntryInvalidated added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryInvalidated(enable bool)

func (*MapEntryListenerConfig) NotifyEntryLoaded added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryLoaded(enable bool)

func (*MapEntryListenerConfig) NotifyEntryMerged added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryMerged(enable bool)

func (*MapEntryListenerConfig) NotifyEntryRemoved added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryRemoved(enable bool)

func (*MapEntryListenerConfig) NotifyEntryUpdated added in v1.0.0

func (c *MapEntryListenerConfig) NotifyEntryUpdated(enable bool)

type MessagePublished added in v1.0.0

type MessagePublished struct {
	TopicName   string
	Value       interface{}
	PublishTime time.Time
	Member      cluster.Member
}

func (*MessagePublished) EventName added in v1.0.0

func (m *MessagePublished) EventName() string

type Queue added in v1.0.0

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

Queue is a concurrent, blocking, distributed, observable queue.

Queue is not a partitioned data-structure. All of the Queue content is stored in a single machine (and in the backup). Queue will not scale by adding more members in the cluster.

func (*Queue) Add added in v1.0.0

func (q *Queue) Add(value interface{}) (bool, error)

Add adds the specified item to this queue if there is available space. Returns true when element is successfully added

func (*Queue) AddAll added in v1.0.0

func (q *Queue) AddAll(values ...interface{}) (bool, error)

AddAll adds the elements in the specified collection to this queue. Returns true if the queue is changed after the call.

func (*Queue) AddListener

func (q *Queue) AddListener(handler QueueItemNotifiedHandler) (types.UUID, error)

AddListener adds an item listener for this queue. Listener will be notified for all queue add/remove events.

func (*Queue) AddListenerIncludeValue

func (q *Queue) AddListenerIncludeValue(handler QueueItemNotifiedHandler) (types.UUID, error)

AddListenerIncludeValue adds an item listener for this queue. Listener will be notified for all queue add/remove events. Received events inclues the updated item.

func (*Queue) AddWithTimeout added in v1.0.0

func (q *Queue) AddWithTimeout(value interface{}, timeout time.Duration) (bool, error)

AddWithTimeout adds the specified item to this queue if there is available space. Returns true when element is successfully added

func (*Queue) Clear added in v1.0.0

func (q *Queue) Clear() error

Clear Clear this queue. Queue will be empty after this call.

func (*Queue) Contains added in v1.0.0

func (q *Queue) Contains(value interface{}) (bool, error)

Contains returns true if the queue includes the given value.

func (*Queue) ContainsAll added in v1.0.0

func (q *Queue) ContainsAll(values ...interface{}) (bool, error)

ContainsAll returns true if the queue includes all given values.

func (Queue) Destroy added in v1.0.0

func (p Queue) Destroy() error

func (*Queue) Drain added in v1.0.0

func (q *Queue) Drain() ([]interface{}, error)

Drain returns all items in the queue and empties it.

func (*Queue) DrainWithMaxSize added in v1.0.0

func (q *Queue) DrainWithMaxSize(maxSize int) ([]interface{}, error)

DrainWithMaxSize returns maximum maxSize items in tne queue and removes returned items from the queue.

func (*Queue) IsEmpty added in v1.0.0

func (q *Queue) IsEmpty() (bool, error)

IsEmpty returns true if the queue is empty.

func (*Queue) Iterator

func (q *Queue) Iterator() ([]interface{}, error)

Iterator returns all of the items in this queue.

func (*Queue) Peek added in v1.0.0

func (q *Queue) Peek() (interface{}, error)

Peek retrieves the head of queue without removing it from the queue.

func (*Queue) Poll added in v1.0.0

func (q *Queue) Poll() (interface{}, error)

Poll retrieves and removes the head of this queue.

func (*Queue) PollWithTimeout added in v1.0.0

func (q *Queue) PollWithTimeout(timeout time.Duration) (interface{}, error)

PollWithTimeout retrieves and removes the head of this queue. Waits until this timeout elapses and returns the result.

func (*Queue) Put added in v1.0.0

func (q *Queue) Put(value interface{}) error

Put adds the specified element into this queue. If there is no space, it waits until necessary space becomes available.

func (*Queue) RemainingCapacity added in v1.0.0

func (q *Queue) RemainingCapacity() (int, error)

RemainingCapacity returns the remaining capacity of this queue.

func (*Queue) Remove added in v1.0.0

func (q *Queue) Remove(value interface{}) (bool, error)

Remove removes the specified element from the queue if it exists.

func (*Queue) RemoveAll added in v1.0.0

func (q *Queue) RemoveAll(values ...interface{}) (bool, error)

RemoveAll removes all of the elements of the specified collection from this queue.

func (*Queue) RemoveListener added in v1.0.0

func (q *Queue) RemoveListener(subscriptionID types.UUID) error

RemoveListener removes the specified listener.

func (*Queue) RetainAll added in v1.0.0

func (q *Queue) RetainAll(values ...interface{}) (bool, error)

RetainAll removes the items which are not contained in the specified collection.

func (*Queue) Size added in v1.0.0

func (q *Queue) Size() (int, error)

Size returns the number of elements in this collection.

func (*Queue) Take added in v1.0.0

func (q *Queue) Take() (interface{}, error)

Take retrieves and removes the head of this queue, if necessary, waits until an item becomes available.

type QueueItemNotified added in v1.0.0

type QueueItemNotified struct {
	QueueName string
	Value     interface{}
	Member    cluster.Member
	EventType int32
}

func (QueueItemNotified) EventName added in v1.0.0

func (q QueueItemNotified) EventName() string

type QueueItemNotifiedHandler added in v1.0.0

type QueueItemNotifiedHandler func(event *QueueItemNotified)

type ReplicatedMap added in v1.0.0

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

func (*ReplicatedMap) AddEntryListener added in v1.0.0

func (m *ReplicatedMap) AddEntryListener(handler EntryNotifiedHandler) (types.UUID, error)

AddEntryListener adds a continuous entry listener to this map.

func (*ReplicatedMap) AddEntryListenerToKey added in v1.0.0

func (m *ReplicatedMap) AddEntryListenerToKey(key interface{}, handler EntryNotifiedHandler) (types.UUID, error)

AddEntryListenerToKey adds a continuous entry listener to this map.

func (*ReplicatedMap) AddEntryListenerToKeyWithPredicate added in v1.0.0

func (m *ReplicatedMap) AddEntryListenerToKeyWithPredicate(key interface{}, predicate predicate.Predicate, handler EntryNotifiedHandler) (types.UUID, error)

AddEntryListenerToKeyWithPredicate adds a continuous entry listener to this map.

func (*ReplicatedMap) AddEntryListenerWithPredicate added in v1.0.0

func (m *ReplicatedMap) AddEntryListenerWithPredicate(predicate predicate.Predicate, handler EntryNotifiedHandler) (types.UUID, error)

AddEntryListenerWithPredicate adds a continuous entry listener to this map.

func (*ReplicatedMap) Clear added in v1.0.0

func (m *ReplicatedMap) Clear() error

Clear deletes all entries one by one and fires related events

func (*ReplicatedMap) ContainsKey added in v1.0.0

func (m *ReplicatedMap) ContainsKey(key interface{}) (bool, error)

ContainsKey returns true if the map contains an entry with the given key

func (*ReplicatedMap) ContainsValue added in v1.0.0

func (m *ReplicatedMap) ContainsValue(value interface{}) (bool, error)

ContainsValue returns true if the map contains an entry with the given value

func (ReplicatedMap) Destroy added in v1.0.0

func (p ReplicatedMap) Destroy() error

func (*ReplicatedMap) Get added in v1.0.0

func (m *ReplicatedMap) Get(key interface{}) (interface{}, error)

Get returns the value for the specified key, or nil if this map does not contain this key. Warning:

This method returns a clone of original value, modifying the returned value does not change the
actual value in the map. One should put modified value back to make changes visible to all nodes.

func (*ReplicatedMap) GetEntrySet added in v1.0.0

func (m *ReplicatedMap) GetEntrySet() ([]types.Entry, error)

GetEntrySet returns a clone of the mappings contained in this map.

func (*ReplicatedMap) GetKeySet added in v1.0.0

func (m *ReplicatedMap) GetKeySet() ([]interface{}, error)

GetKeySet returns keys contained in this map

func (*ReplicatedMap) GetValues added in v1.0.0

func (m *ReplicatedMap) GetValues() ([]interface{}, error)

GetValues returns a list clone of the values contained in this map

func (*ReplicatedMap) IsEmpty added in v1.0.0

func (m *ReplicatedMap) IsEmpty() (bool, error)

IsEmpty returns true if this map contains no key-value mappings.

func (*ReplicatedMap) Put added in v1.0.0

func (m *ReplicatedMap) Put(key interface{}, value interface{}) (interface{}, error)

Put sets the value for the given key and returns the old value.

func (*ReplicatedMap) PutAll added in v1.0.0

func (m *ReplicatedMap) PutAll(keyValuePairs []types.Entry) error

PutAll copies all of the mappings from the specified map to this map. No atomicity guarantees are given. In the case of a failure, some of the key-value tuples may get written, while others are not.

func (*ReplicatedMap) Remove added in v1.0.0

func (m *ReplicatedMap) Remove(key interface{}) (interface{}, error)

Remove deletes the value for the given key and returns it.

func (*ReplicatedMap) RemoveEntryListener added in v1.0.0

func (m *ReplicatedMap) RemoveEntryListener(subscriptionID types.UUID) error

RemoveEntryListener removes the specified entry listener.

func (*ReplicatedMap) Size added in v1.0.0

func (m *ReplicatedMap) Size() (int, error)

Size returns the number of entries in this map.

type SerializationConfigBuilder

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

func (*SerializationConfigBuilder) AddClassDefinition

func (*SerializationConfigBuilder) AddCustomSerializer

AddCustomSerializer adds a customer serializer for the given type.

func (*SerializationConfigBuilder) AddIdentifiedDataSerializableFactory

AddIdentifiedDataSerializableFactory adds an identified data serializable factory.

func (*SerializationConfigBuilder) AddPortableFactory

AddPortableFactory adds a portable factory.

func (*SerializationConfigBuilder) SetBigEndian

SetBigEndian sets byte order to big endian. If set to false, little endian byte order is used. Default byte order is big endian.

func (*SerializationConfigBuilder) SetGlobalSerializer

SetGlobalSerializer sets the global serializer

type Topic added in v1.0.0

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

Topic is a distribution mechanism for publishing messages that are delivered to multiple subscribers, which is also known as a publish/subscribe (pub/sub) messaging model.

Publish and subscriptions are cluster-wide. When a member subscribes for a topic, it is actually registering for messages published by any member in the cluster, including the new members joined after you added the listener.

Messages are ordered, meaning that listeners(subscribers) will process the messages in the order they are actually published.

func (*Topic) AddListener

func (t *Topic) AddListener(handler TopicMessageHandler) (types.UUID, error)

AddListener adds a subscriber to this topic.

func (Topic) Destroy added in v1.0.0

func (p Topic) Destroy() error

func (*Topic) Publish added in v1.0.0

func (t *Topic) Publish(message interface{}) error

Publish publishes the given message to all subscribers of this topic.

func (*Topic) PublishAll added in v1.0.0

func (t *Topic) PublishAll(messages ...interface{}) error

PublishAll published all given messages to all subscribers of this topic.

func (*Topic) RemoveListener added in v1.0.0

func (t *Topic) RemoveListener(subscriptionID types.UUID) error

RemoveListener removes the given subscription from this topic.

type TopicMessageHandler added in v1.0.0

type TopicMessageHandler func(event *MessagePublished)

type ValidationError

type ValidationError interface {
	error
}

Directories

Path Synopsis
Package serialization serializes user objects to Data and back to Object.
Package serialization serializes user objects to Data and back to Object.
Package types contains various helper types.
Package types contains various helper types.
internal
cb
it
proto/codec
* Copyright (c) 2008-2021, Hazelcast, Inc.
* Copyright (c) 2008-2021, Hazelcast, Inc.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL