Tair (Redis® OSS-Compatible):exString

Présentation

Les chaînes Redis natives stockent une paire clé-valeur. TairString ajoute un numéro de version à chaque clé, offrant ainsi un mécanisme léger de détection des conflits sans coordination externe. Chaque écriture réussie incrémente la version de 1 ; toute écriture spécifiant une version incorrecte est rejetée.

TairString vous permet également de définir une limite minimale ou maximale pour les commandes EXINCRBY et EXINCRBYFLOAT. Si une incrémentation devait pousser la valeur en dehors de cette plage, la commande renvoie une erreur au lieu d'écrire la valeur hors limites.

Fonctionnalités principales

• Chaque clé TairString contient un numéro de version associé à sa valeur.

• EXSET et EXINCRBY acceptent l'option VER qui rejette les écritures lorsque la version a changé depuis la dernière lecture de la clé, implémentant ainsi une opération de comparaison-et-définition (compare-and-set) sans transaction séparée.

• EXINCRBY et EXINCRBYFLOAT acceptent les options MIN et MAX qui plafonnent le compteur dans une plage définie.

Ce module est open source. Pour plus d'informations, consultez GitHub.

127.0.0.1:6379> EXSET foo 100
OK
127.0.0.1:6379> EXGET foo
1) "100"
2) (integer) 1
127.0.0.1:6379> EXSET foo 200 VER 1
OK
127.0.0.1:6379> EXGET foo
1) "200"
2) (integer) 2
127.0.0.1:6379> EXSET foo 300 VER 1
(error) ERR update version is stale
127.0.0.1:6379> EXCAS foo 400 2
1) OK
2)
3) (integer) 3
127.0.0.1:6379> EXCAD foo 3
(integer) 1

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Une instance Tair basée sur DRAM ou optimisée pour la mémoire persistante dont la version mineure est 1.2.3 ou ultérieure

La dernière version mineure offre davantage de fonctionnalités et une stabilité accrue. Mettez à jour l'instance vers la dernière version mineure. Pour plus d'informations, consultez Mettre à jour la version mineure d'une instance . Pour les instances en cluster ou avec séparation lecture/écriture, mettez également à jour les nœuds proxy vers la dernière version mineure afin de garantir le bon fonctionnement de toutes les commandes.

Notes d'utilisation

Les données TairString sont stockées sur une instance Tair. Les chaînes Redis natives et les TairStrings peuvent coexister sur la même instance Tair, mais les chaînes Redis natives ne prennent pas en charge les commandes décrites dans cette rubrique.

Récapitulatif des commandes

Conventions de syntaxe

• MAJUSCULES : mot-clé de commande.

• italique : variable.

• [options] : paramètre facultatif. Les paramètres sans crochets sont obligatoires.

• A|B : options mutuellement exclusives ; spécifiez-en une seule.

• ... : le paramètre précédent peut être répété.

EXSET

Paramètres

• key : la clé à écrire.

• value : la valeur à écrire.

• EX time : durée d'expiration relative en secondes. 0 signifie que la clé expire immédiatement. Si omis, la clé n'expire pas.

• EXAT time : durée d'expiration absolue en secondes (horodatage Unix). 0 signifie que la clé expire immédiatement. Si omis, la clé n'expire pas.

• PX time : durée d'expiration relative en millisecondes. 0 signifie que la clé expire immédiatement. Si omis, la clé n'expire pas.

• PXAT time : durée d'expiration absolue en millisecondes (horodatage Unix). 0 signifie que la clé expire immédiatement. Si omis, la clé n'expire pas.

• NX : écriture uniquement si la clé n'existe pas.

• XX : écriture uniquement si la clé existe déjà.

• VER version : opération compare-and-set par numéro de version.

  • Si la clé existe : l'écriture réussit uniquement si la version spécifiée correspond à la version actuelle ; la version est alors incrémentée de 1. Si les versions ne correspondent pas, une erreur est renvoyée.

  • Si la clé n'existe pas ou si sa version actuelle est 0 : la valeur VER est ignorée, l'écriture réussit et la version est définie sur 1.

• ABS version : écrase la version de manière inconditionnelle. Après l'écriture, la version est égale à la valeur ABS spécifiée.

• KEEPTTL : conserve le TTL (time-to-live) restant de la clé. Ne peut pas être combiné avec EX, PX, EXAT ou PXAT.

Si aucun paramètre d'expiration n'est défini ( EX , PX , EXAT , PXAT ou KEEPTTL ), la clé n'expire pas.

Valeurs de retour

• OK : l'écriture a réussi.

• nil : XX a été spécifié mais la clé n'existe pas, ou NX a été spécifié mais la clé existe déjà.

• Erreur : tous les autres échecs.

Exemple

EXSET foo bar EX 10 NX ABS 100

OK

EXGET

Paramètres

• key : la clé à lire.

Valeurs de retour

• Un tableau contenant la valeur (chaîne binaire) et le numéro de version (entier).

• Erreur : la clé n'existe pas ou un autre échec s'est produit.

Exemple

EXGET foo

1) "bar"
2) (integer) 1

EXSETVER

Paramètres

• key : la clé à mettre à jour.

• version : le numéro de version à attribuer.

Valeurs de retour

• 1 : la version a été définie avec succès.

• 0 : la clé n'existe pas.

• Erreur : un autre échec s'est produit.

Exemple

EXSETVER foo 2

(integer) 1

EXINCRBY

Paramètres

• key : la clé à mettre à jour.

• num : le montant entier à ajouter (utilisez une valeur négative pour décrémenter).

• EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL : identiques à EXSET.

• MIN minval : la valeur minimale autorisée. Si le résultat est inférieur à minval, la commande renvoie une erreur et n'écrit pas.

• MAX maxval : la valeur maximale autorisée. Si le résultat dépasse maxval, la commande renvoie une erreur et n'écrit pas.

Si aucun paramètre d'expiration n'est défini ( EX , PX , EXAT , PXAT ou KEEPTTL ), la clé n'expire pas.

Valeurs de retour

• La valeur mise à jour (entier) : l'incrémentation a réussi.

• (error) ERR increment or decrement would overflow : le résultat tomberait en dehors de la plage MIN/MAX.

• Erreur : un autre échec s'est produit.

Exemple

L'exemple suivant suppose que EXSET foo 1 a été exécuté auparavant. La commande incrémente foo de 100 et limite la valeur à un maximum de 300.

EXINCRBY foo 100 MAX 300

(integer) 101

Modèle : compteur borné

Utilisez MIN et MAX pour implémenter un limiteur de débit ou un compteur de quota qui ne dépasse jamais ses limites :

# Initialize the counter
EXSET requests 0

# Increment on each request; reject when the limit is hit
EXINCRBY requests 1 MAX 100
# Returns (error) ERR increment or decrement would overflow when the limit is reached

EXINCRBYFLOAT

Paramètres

• key : la clé à mettre à jour.

• num : le montant à virgule flottante à ajouter (utilisez une valeur négative pour décrémenter).

• Toutes les autres options (EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL, MIN, MAX) : identiques à EXINCRBY.

Si aucun paramètre d'expiration n'est défini ( EX , PX , EXAT , PXAT ou KEEPTTL ), la clé n'expire pas.

Valeurs de retour

• La valeur mise à jour : l'incrémentation a réussi.

• (error) ERR increment or decrement would overflow : le résultat tomberait en dehors de la plage MIN/MAX.

• Erreur : un autre échec s'est produit.

Exemple

L'exemple suivant suppose que EXSET foo 1 a été exécuté auparavant.

EXINCRBYFLOAT foo 10.123

(integer) 11.123

EXCAS

Paramètres

• key : la clé à mettre à jour.

• newvalue : la valeur à écrire si la version correspond.

• version : le numéro de version à comparer avec la version actuelle.

Valeurs de retour

• ["OK", "", latest_version] : la mise à jour a réussi. La chaîne vide au milieu n'a aucune signification.

• ["ERR update version is stale", current_value, current_version] : la version ne correspondait pas. La clé n'a pas été modifiée.

• -1 : la clé n'existe pas.

• Erreur : un autre échec s'est produit.

Exemple

L'exemple suivant suppose que EXSET foo bar a été exécuté auparavant (version = 1).

EXCAS foo bzz 1

1) OK
2)
3) (integer) 2

Modèle : verrouillage optimiste

Utilisez EXCAS pour implémenter une boucle lecture-modification-écriture sans verrous :

# 1. Read the current value and version
EXGET mykey
# Returns: value="old", version=5

# 2. Modify locally

# 3. Write back only if the version hasn't changed
EXCAS mykey "new" 5
# If another writer changed the key, EXCAS returns the stale-version error.
# Retry from step 1.

EXCAD

Paramètres

• key : la clé à supprimer.

• version : le numéro de version à comparer avec la version actuelle.

Valeurs de retour

• 1 : la clé a été supprimée.

• 0 : la version ne correspondait pas ; la clé n'a pas été supprimée.

• -1 : la clé n'existe pas.

• Erreur : un autre échec s'est produit.

Exemple

L'exemple suivant suppose que EXSET foo bar a été exécuté auparavant (version = 1).

EXCAD foo 1

(integer) 1

Étapes suivantes

• Implémenter des verrous distribués haute performance à l'aide de TairString

• Implémenter un verrouillage optimiste haute performance à l'aide de TairString

• Implémenter des compteurs bornés à l'aide de TairString