Carte triée dans le stock de mémoire

La structure de données de la carte triée des magasins de mémoire permet de stocker des données fréquentes en mémoire sous forme de paires clé-valeur avec une clé de tri facultative et de maintenir un ordre spécifique en fonction des clés de tri et des clés.Contrairement aux files d'attente, l'ordre des clés entrant dans une carte ne détermine pas l'ordre de traitement, ce qui rend les cartes triées utiles pour trier les organisations de données basées sur des données pour implémenter des entités d'expérience telles que des classements et des enchères sur plusieurs serveurs.

Limites

En plus des limites de taille de la structure de données , les cartes triées ont une limite de taille de clé de 128 caractères, une limite de taille de valeur de 32 KB et une limite de taille de clé de tri de 128 caractères.

Si vous devez stocker des données qui dépassent cette limite pour votre expérience, vous pouvez adopter la technique de fragmentation pour les diviser et les distribuer à travers préfixe de clé dans plusieurs structures de données.Les magasins de mémoire éclatés peuvent également aider à améliorer la scalabilité de votre système.

Obtenir une carte triée

Pour obtenir une carte triée, appelez MemoryStoreService:GetSortedMap() avec un nom que vous voulez définir pour la carte.Le nom est global dans l'expérience, vous pouvez donc accéder à la même carte triée sur n'importe quel script en utilisant le nom.

Obtenir une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Après avoir obtenu une carte triée, appelez l'une des fonctions suivantes pour lire ou écrire des données dedans :

Ajouter ou écraser des données

Pour ajouter une nouvelle clé ou écraser la valeur ou la clé de tri d'une clé dans la carte triée, appelez avec la clé nom , sa valeur , un temps d'expiration en secondes et une clé de tri optionnelle .La mémoire se nettoie automatiquement une fois que la clé expire.Le temps d'expiration maximum est de 3 888 000 secondes (45 jours).La clé de tri, si elle est fournie, doit être un nombre valide (entier ou point flottant) ou une chaîne.

Dans l'ordre de tri de vos clés, une clé de tri a la priorité sur une clé.Par exemple, lors du tri par ordre croissant, les clés de tri numériques sont triées en premier, suivies des clés de tri de chaîne, puis des articles sans clé de tri.Tous les éléments avec des clés de tri numériques sont triés par clé de tri, si la clé de tri pour deux éléments est égale, ils sont triés par clé.De même, tous les éléments avec des clés de tri de chaîne sont triés par clé de tri, si la clé de tri pour deux éléments est égale, ils sont triés par clé.Tous les éléments sans clé de tri sont triés simplement par la clé.

Exemple de certaines données triées par ordre croissant -

{Key: "player1", Value: someValue1, SortKey: -1}
{Key: "player2", Value: someValue2, SortKey: 0}
{Key: "player4", Value: someValue3, SortKey: 1}
{Key: "player5", Value: someValue4, SortKey: 1}
{Key: "player3", Value: someValue5, SortKey: 3.14}
{Key: "player6", Value: someValue6, SortKey: "someString"}
{Key: "player0", Value: someValue7}
{Key: "player7", Value: someValue8}

Notez comment player0 trier après toutes les clés avec une clé de tri.player6 trie après toutes les clés avec une clé de tri numérique.player4 et player5 ont la même clé de tri, donc elles sont triées par ordre croissant par clé.

Ajouter des données à une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Set succeeded.")
end

Obtenir des données

Vous pouvez soit obtenir une valeur de données et trier la clé associée à une clé spécifique, soit obtenir plusieurs valeurs et trier les clés pour les clés dans une plage.

Obtenir des données avec une clé

Pour obtenir une valeur et trier une clé associée à une clé d'une carte triée, appelez avec le nom de clé .

Obtenir une clé spécifique à partir d'une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Set succeeded.")
end

local item
local getSuccess, getError = pcall(function()
	item = sortedMap:GetAsync("User_1234")
end)
if getSuccess then
	print(item)
else
	warn(getError)
end

Obtenir des données avec plusieurs clés

Pour obtenir des données pour plusieurs clés à partir de la carte triée comme une seule opération, appelez MemoryStoreSortedMap:GetRangeAsync() .Cette fonction liste par défaut toutes les clés existantes, mais vous pouvez définir les limites supérieure et inférieure pour la plage de clés.Par exemple, l'échantillon de code suivant récupère jusqu'à 20 éléments à partir du début de la carte triée, avec des clés plus grandes ou égales à 10 , des clés de tri plus grandes ou égales à 100 et des clés inférieures ou égales à 50 , des clés de tri inférieures ou égales à 500 .

Obtenir une gamme de clés à partir d'une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local lowerBound = {}
lowerBound["key"] = "10"
lowerBound["sortKey"] = 100
local upperBound = {}
upperBound["key"] = "50"
upperBound["sortKey"] = 500

-- Obtenez jusqu'à 20 articles à partir du début
local getSuccess, items = pcall(function()
	return sortedMap:GetRangeAsync(
		Enum.SortDirection.Ascending, 20, lowerBound, upperBound)
end)
if getSuccess then
	for _, item in items do
		print(item.key)
		print(item.sortKey)
	end
end

Mettre à jour les données

Pour récupérer la valeur et le tri de la clé d'une clé à partir d'une carte triée et la mettre à jour, appelez avec le nom de clé et une fonction d'appel de rappel pour mettre à jour la valeur et le tri de cette clé, et un temps d'expiration en secondes.Le temps d'expiration maximum est de 3 888 000 secondes (45 jours).

Pour la plupart des expériences, plusieurs serveurs peuvent mettre à jour la même clé simultanément et modifier sa valeur.Comme UpdateAsync() modifie toujours la dernière valeur avant de mettre à jour, vous devez l'utiliser pour lire la dernière valeur en tant qu'entrée pour votre fonction de rappel.

Par exemple, l'exemple de code suivant met à jour le score dans un classement pour un joueur dans une partie.Le score est calculé comme des éliminations / des décès.UpdateAsync() garantit que les éliminations et les décès sont mis à jour pour les valeurs les plus récentes, même si plusieurs serveurs de jeu mettent à jour le même élément simultanément.Les éliminations et les décès d'un joueur augmentent de manière monotone et ne peuvent donc augmenter en valeur qu'au cours d'une session.

Mise à jour du score du classement pour un joueur dans une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("Leaderboard")

local function updateLeaderboard(itemKey, killsToAdd, deathsToAdd)
	local success, newStats, newScore = pcall(function()
		return sortedMap:UpdateAsync(itemKey, function(playerStats, playerScore)
			playerStats = playerStats or { kills = 0, deaths = 0 }
			playerStats.kills += killsToAdd
			playerStats.deaths += deathsToAdd
			if playerStats then
				-- `playerScore` est la clé de tri utilisée pour trier les éléments de la carte
				playerScore = playerStats.kills / math.max(playerStats.deaths, 1)
				return playerStats, playerScore
			end
			return nil
		end, 30)
	end)
	if success then
		print(newStats)
		print(newScore)
	end
end

Le délai pour UpdateAsync() est similaire à GetAsync() et SetAsync() à moins qu'il y ait une compétition.

Lorsque la controverse se produit, le système réessaie automatiquement l'opération jusqu'à ce que l'une de ces trois choses se produise : l'opération réussit, la fonction de rappel retourne nil ou le nombre maximum de tentatives est atteint.Si le système atteint le nombre maximum de réessais, il renvoie un conflit.

Supprimer des données

Vous pouvez utiliser MemoryStoreSortedMap:RemoveAsync() pour supprimer une clé de la carte triée et supprimer toutes les données dans une carte triée dans un stock de mémoire.

Supprimer une clé

Pour supprimer une clé de la carte triée, appelez avec un nom de clé .

Supprimer une clé d'une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, "someStringSortKey")
end)
if setSuccess then
	print("Set succeeded.")
end

local removeSuccess, removeError = pcall(function()
	sortedMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
	warn(removeError)
end

Supprimer toutes les données

Pour supprimer la mémoire dans des cartes triées, listez toutes vos clés avec MemoryStoreSortedMap:GetRangeAsync() , puis supprimez-les avec MemoryStoreSortedMap:RemoveAsync() .

Supprimer la mémoire dans une carte triée
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Limite inférieure initiale de zéro commence à partir du premier item
local exclusiveLowerBound = nil

while true do
	-- Obtenez jusqu'à cent éléments à partir de la limite inférieure actuelle
	local getRangeSuccess, items = pcall(function()
		return sortedMap:GetRangeAsync(Enum.SortDirection.Ascending, 100, exclusiveLowerBound)
	end)
	if getRangeSuccess then
		local removeSuccess = true
		local removeError = nil

		for _, item in items do
			removeSuccess, removeError = pcall(function()
				sortedMap:RemoveAsync(item.key)
			end)
		end

		-- S'il y a eu une erreur en supprimant des éléments, réessayez avec la même limite inférieure exclusive
		if not removeSuccess then
			warn(removeError)
		-- Si la portée est inférieure à cent éléments, la fin de la carte est atteinte
		elseif #items < 100 then
			break
		else
			-- La dernière clé récupérée est la limite inférieure exclusive pour la prochaine itération
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end