SharedTable
*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.
Représente une structure de données semblable à une table qui peut être partagée entre les contextes d'exécution.Bien qu'il puisse être utilisé pour divers types de stockage de données générales, il est conçu spécialement pour être utilisé avec Parallel Luau, où il peut être utilisé pour partager l'état à travers les scripts appartenant à différentes instances Actor.
Il existe quelques façons idiomatiques de communiquer des tables partagées entre les scripts.Une méthode consiste à stocker et à récupérer SharedTable des objets dans le SharedTableRegistry.Le registre permet à n'importe quel script dans le même modèle de données d'obtenir ou de définir un SharedTable par nom.Une autre méthode consiste à utiliser Actor:SendMessage() pour envoyer une table partagée à une autre Actor dans un message.
Comme une table Luau, un objet SharedTable stocke un ensemble de paires de valeur clé.Contrairement à une table Luau, seuls les types d'objets sélectionnés peuvent être stockés dans une table partagée, similaire à d'autres restrictions que vous trouverez ailleurs dans le moteur Roblox.
Les clés doivent être (1) une chaîne ou (2) un nombre entier négatif inférieur à 2 32 . D'autres types de clés ne sont pas pris en charge.
Les valeurs doivent avoir l'un des types suivants : Boolean, Number, Vector, String, SharedTable ou un taperde données serialisable.La capacité de stocker un SharedTable comme valeur dans un autre SharedTable permet la construction de structures de données imbriquées et récursives.
SharedTable les objets sont distincts et différents SharedTable les objets ne se comparent jamais à l'égal, même s'ils ont des contenus qui se comparent à l'égal.
Comme une table Luau, un objet SharedTable peut être gelé, auquel cas il est en lecture seule.Une tentative de modification d'un élément gelé SharedTable provoquera une erreur.Un SharedTable peut être créé en d'abord créant un (non gelé, modifiable) SharedTable avec le contenu souhaité, puis en appelant SharedTable.cloneAndFreeze() pour créer une copie gelée de celui-ci.
Échantillons de code
Elements in a SharedTable are accessed in the same way as elements of Luau tables, using the st[k] syntax or, for string keys, st.k.
local st = SharedTable.new()
st[1] = "a"
st["x"] = true
st.y = 5
assert(st[1] == "a")
assert(st["x"] == true)
assert(st.x == true)
assert(st["y"] == 5)
assert(st.y == 5)
-- true is not a valid SharedTable key, so attempting to set that key
-- fails:
assert(not pcall(function() st[true] = 100 end))
-- A function is not a valid SharedTable value, so attempting to set a
-- value to a function fails:
assert(not pcall(function() st["f"] = function() end end))The for loop can be used to iterate over the elements of a SharedTable. The elements of the SharedTable are not iterated directly. Instead, a shallow clone is made of the SharedTable, and its elements are iterated. This is done to ensure that a consistent view of the SharedTable is maintained throughout the iteration. Thus, both of the following for loops have the same behavior.
Note that this means that if the SharedTable is accessed directly from within the body of the iteration loop, its state may not be consistent with the state observed through the iteration.
The iteration order is partially specified. Elements with numeric keys are iterated before elements with string keys. Elements with numeric keys are iterated in ascending numeric order. Elements with string keys are iterated in an unspecified order.
local st = SharedTable.new({"a", "b", "c"})
for k, v in SharedTable.clone(st, false) do
print(k, ": ", v)
end
for k, v in st do
print(k, ": ", v)
endRésumé
Constructeurs
- new()
Retourne un nouveau, vide SharedTable.
Renvoie un nouveau SharedTable contenant des éléments équivalents à ceux de la table Luau fournie.
Fonctions
Supprime tous les éléments de la SharedTable .
Crée et renvoie une copie du clone fourni SharedTable .
Crée et renvoie une clone gelée (lecture seule) du SharedTable.
Ajoute delta à la valeur avec la clé fournie et renvoie la valeur originale.
Retourne true si le SharedTable est gelé (lecture seule).
Retourne le nombre d'éléments stockés dans le SharedTable.
Mise à jour de la valeur avec la clé fournie via la fonction de mise à jour fournie.
Constructeurs
new
Renvoie un nouveau SharedTable contenant des éléments équivalents à ceux de la table Luau fournie.
Si la table Luau fournie contient des clés ou des valeurs qui ne peuvent pas être stockées dans un SharedTable, la construction du SharedTable échoue.Voir le résumé en haut de cette page pour une liste des types d'objets qui peuvent être stockés dans un SharedTable .Si la table Luau contient une table en tant que valeur, cette table est convertie en une nouvelle SharedTable.
Notez qu'il peut être souhaitable, dans certains cas, de stocker un SharedTable dans le SharedTableRegistry.La méthode Class.ShareTableRegistry:GetSharedTable() fournit une façon pratique de le faire.
Paramètres
La table Luau dont les éléments doivent être stockés dans la nouvelle SharedTable.
Fonctions
clear
Supprime atomiquement tous les éléments d'un SharedTable .
Si le SharedTable est gelé, l'opération échoue et une erreur se produit.
Paramètres
Le SharedTable à effacer.
Retours
clone
Crée une copie de un SharedTable et retourne la copie.
Si l'argument facultatif deep n'est pas présent, ou s'il est présent et que sa valeur est false, alors une clone superficielle est créée.Un clone superficiel ne copie que l'objet de niveau supérieur SharedTable.Si une valeur dans le SharedTable lui-même est un SharedTable, alors à la fois l'original SharedTable et le clone SharedTable se référeront au même SharedTable.
L'opération de clone superficielle est atomique, donc le clone SharedTable contiendra une capture instantanée cohérente de l'état dans l'original SharedTable, même si elle est modifiée simultanément par d'autres scripts.
Si l'argument facultatif deep optionnel est présent et sa valeur est true, alors une clonage profond est créé.Un clone profond copie récursivement une structure de SharedTable objets telle qu'il n'y a pas d'état partagé entre l'original SharedTable et le clone.
Le clone de chaque SharedTable dans le graph des objets SharedTable est atomique, mais le clone profond dans son ensemble n'est pas atomique.Ainsi, la copie de chaque SharedTable dans le graph contiendra une sauvegarde cohérente de l'état de l'objet original SharedTable duquel il a été cloné, mais les états des différents objets SharedTable peuvent être incohérents si le graph est modifié simultanément à partir d'autres scripts.
Les objets SharedTable clonés peuvent être gelés (lecture seule) ou non.Quoi qu'il en soit, les clones nouvellement créés ne sont pas gelés (et sont donc modifiables).Pour créer des clones gelés, utilisez la fonction SharedTable.cloneAndFreeze.
Pour illustrer la différence entre un clone superficiel et un clone profond, envisagez les échantillons suivants.Cette première échantillon crée un clone superficiel et la deuxième crée un clone profond.
Paramètres
L'objet SharedTable à cloner.
Créer un clone profond ( true ) ou un clone superficiel ( false ).
Retours
Échantillons de code
This code sample creates a shallow clone of a SharedTable.
local original = SharedTable.new()
original["a"] = "original a"
original["b"] = "original b"
original["c"] = SharedTable.new()
original["c"]["d"] = "original d"
local clone = SharedTable.clone(original, false)
clone["a"] = "new a"
clone["b"] = "new b"
clone["c"]["d"] = "new d"
assert(original["a"] == "original a")
assert(original["b"] == "original b")
-- Because this was a shallow clone, original["c"] and clone["c"] are
-- the same SharedTable object.
assert(original["c"] == clone["c"])
assert(original["c"]["d"] == "new d")This code sample creates a deep clone of a SharedTable.
local original = SharedTable.new()
original["a"] = "original a"
original["b"] = "original b"
original["c"] = SharedTable.new()
original["c"]["d"] = "original d"
local clone = SharedTable.clone(original, true)
clone["a"] = "new a"
clone["b"] = "new b"
clone["c"]["d"] = "new d"
assert(original["a"] == "original a")
assert(original["b"] == "original b")
-- Because this was a deep clone, clone["c"] is a clone of original["c"];
-- they are distinct SharedTable objects.
assert(original["c"] ~= clone["c"])
assert(original["c"]["d"] == "original d")cloneAndFreeze
Crée une clone gelée (lecture seule) d'un SharedTable et renvoie le clone.Le comportement de cette fonction est le même que celui du clone, sauf que le clone est gelé.
Si une clonage profond est demandé, alors tous les objets clonés SharedTable sont gelés.
Paramètres
L'objet SharedTable à cloner.
Créer un clone profond ( true ) ou un clone superficiel ( false ).
Retours
increment
Augmente atomiquement la valeur d'un élément.Un élément avec la clé spécifiée doit exister dans le SharedTable, et il doit être de type number.La valeur spécifiée delta est ajoutée à la valeur et la valeur originale est retournée.
La fonction SharedTable.update peut également être utilisée à cet effet ; cette fonction increment existe pour des raisons de commodité et de performance (en général, increment est beaucoup plus rapide que update, il est donc préférable de l'utiliser là où cela est possible).Les deux appels de fonction suivants ont le même effet :
local st = SharedTable.new()
st["x"] = 1
local oldValue = SharedTable.increment(st, "x", 1)
SharedTable.update(st, "x", function(v)
oldValue = v
return v + 1
end)
Si le SharedTable est gelé, l'opération échoue et une erreur se produit.
Paramètres
L'objet SharedTable à mettre à jour.
La clé de l'élément dans l'objet SharedTable à mettre à jour.
La valeur à ajouter à l'élément dans le SharedTable .
Retours
La valeur originale de l'élément, avant delta qu'il a été ajouté à elle.
Échantillons de code
This code sample demonstrates usage of SharedTable.increment().
local st = SharedTable.new()
st["x"] = 1
local oldValue = SharedTable.increment(st, "x", 1)
assert(oldValue == 1)
assert(st["x"] == 2)
-- The value of the specified key must be a number. If it is not a
-- number, the call will fail:
st["y"] = "test"
assert(not pcall(function() SharedTable.increment(st, "y", 1) end))isFrozen
Retourne true si le SharedTable est gelé (lecture seule).
Paramètres
L'objet SharedTable dont l'état gelé doit être interrogé.
Retours
size
Retourne le nombre d'éléments stockés dans la table partagée.Notez que si d'autres scripts modifient simultanément la table partagée, la taille renvoyée peut ne plus être correcte après son retour, car d'autres scripts peuvent avoir ajouté ou supprimé des éléments de la table partagée.
Paramètres
L'objet SharedTable dont la taille doit être interrogée.
Retours
update
Mise à jour atomique de la valeur d'un élément.
Lorsqu'un SharedTable est accédé simultanément à partir de scripts s'exécutant dans des contextes d'exécution différents, il est possible que leurs accès se mélangent de manière imprévisible.Pour cette raison, le code comme le suivant est généralement incorrect, car la valeur peut avoir changé entre la lecture sur la première ligne et la mise à jour sur la deuxième ligne :
La fonction de mise à jour permet d'effectuer une mise à jour atomique d'un élément.Il prend une fonction qu'il appellera avec la valeur actuelle de l'élément.La fonction peut ensuite calculer et retourner la nouvelle valeur.Notez que la fonction peut être appelée plusieurs fois si la SharedTable est modifiée simultanément à partir d'autres scripts.
Si le SharedTable est gelé, l'opération échoue et une erreur se produit.
Paramètres
L'objet SharedTable à mettre à jour.
La clé de l'élément dans l'objet SharedTable à mettre à jour.
La fonction qui sera appelée pour calculer la nouvelle valeur pour l'élément.
Retours
Échantillons de code
This code sample demonstrates usage of SharedTable.update().
local st = SharedTable.new()
st["x"] = "abcd"
SharedTable.update(st, "x", function(v)
assert(v == "abcd")
return v .. "e"
end)
assert(st["x"] == "abcde")