Carte de hachage de magasin mémoire

Les cartes de hachage, similaires aux cartes triées, vous permettent de stocker des données en mémoire sous forme de paires clé-valeur. Contrairement aux cartes triées, elles ne conservent aucune garantie d'ordre. Cette structure de données est utile pour les cas nécessitant une mise en cache simple des données et un accès rapide, comme les inventaires partagés, les maisons de ventes aux enchères physiques, et plus encore. Les cartes de hachage gèrent automatiquement le partitionnement de vos données et sont très utiles si vous avez plus de 1 000 clés. Pour des espaces de clés plus petits, nous vous recommandons les cartes triées.

Limites

Les cartes de hachage ont une limite de taille de clé de 128 caractères et une limite de taille de valeur de 32 Ko.

Sinon, les cartes de hachage utilisent les mêmes limites de requêtes API et de quota mémoire que les autres structures de données de magasin mémoire.

Obtenir une carte de hachage

Pour obtenir une carte de hachage, appelez MemoryStoreService:GetHashMap() avec un nom pour la carte de hachage. Le nom est global au sein du jeu, vous pouvez donc accéder à la même carte de hachage dans n'importe quel script en utilisant ce nom.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

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

Pour des documents approfondis sur chaque fonction, voir MemoryStoreHashMap.

Ajouter ou écraser des données

Pour ajouter une nouvelle clé ou écraser la valeur d'une clé dans la carte de hachage, appelez MemoryStoreHashMap:SetAsync() avec le nom de la clé, sa valeur, et un temps d'expiration en secondes. La mémoire se nettoie automatiquement une fois la clé expirée. Le temps d'expiration maximal est de 3 888 000 secondes (45 jours).

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("L'ajout a réussi.")
end

Obtenir des données

Vous pouvez soit obtenir une valeur associée à une clé spécifique, soit obtenir plusieurs paires clé-valeur dans la carte de hachage.

Obtenir des données avec une clé

Pour obtenir une valeur associée à une clé de la carte de hachage, appelez MemoryStoreHashMap:GetAsync() avec le nom de la clé.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("L'ajout a réussi.")
end

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

Obtenir des données avec plusieurs paires clé-valeur

Pour obtenir toutes les paires clé-valeur de la carte de hachage en une seule opération, appelez MemoryStoreHashMap:ListItemsAsync() avec la taille de page souhaitée. Cette fonction liste toutes les clés existantes de manière paginée. Par exemple, l'exemple de code suivant récupère jusqu'à 32 éléments de la carte de hachage.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des éléments, 32 éléments à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		-- Itérer à travers toutes les paires clé-valeur de la page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avancer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end

Mettre à jour des données

Pour récupérer la valeur d'une clé d'une carte de hachage et la mettre à jour, appelez MemoryStoreHashMap:UpdateAsync() avec le nom de la clé, une fonction de rappel pour mettre à jour la clé, et un temps d'expiration en secondes.

Pour la plupart des jeux, plusieurs serveurs peuvent mettre à jour la même clé simultanément et changer la valeur. Comme UpdateAsync() modifie toujours la valeur la plus récente avant de mettre à jour, vous devez l'utiliser pour lire la dernière valeur comme entrée pour votre fonction de rappel.

Par exemple, l'exemple de code suivant met à jour le compte de ressources d'une ressource dans un inventaire partagé. UpdateAsync() garantit que toutes les contributions des joueurs seront intégrées dans cet inventaire partagé, même si ces contributions sont faites simultanément. Dans cette fonction, elle impose également un nombre maximum de ressources de 500.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")

local function contributeResources(itemResource, addedCount)
	local success, newResourceCount = pcall(function()
		return hashMap:UpdateAsync(itemResource, function(resource)
			resource = resource or {count = 0}
			resource.count = resource.count + addedCount

			-- s'assurer que nous ne dépassons pas le nombre maximum de ressources
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

La latence pour UpdateAsync() est similaire à celle de GetAsync() et SetAsync() à moins qu'il n'y ait une contention.

Lorsque la contention se produit, le système réessaie automatiquement l'opération jusqu'à ce que l'un des trois événements suivants se produise : l'opération réussit, la fonction de rappel renvoie nil, ou le nombre maximum de tentatives est atteint. Si le système atteint le nombre maximum de tentatives, il renvoie un conflit.

Supprimer des données

Vous pouvez utiliser MemoryStoreHashMap:RemoveAsync() à la fois pour supprimer une clé de la carte de hachage et pour supprimer toutes les données dans une carte de hachage de magasin mémoire.

Supprimer une clé

Pour supprimer une clé de la carte de hachage, appelez MemoryStoreHashMap:RemoveAsync() avec le nom de la clé.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("L'ajout a réussi.")
end

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

Supprimer toutes les données

Pour supprimer toutes les données dans une carte de hachage, listez tous vos éléments avec MemoryStoreHashMap:ListItemsAsync(), puis retirez-les avec MemoryStoreHashMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des éléments, 32 éléments à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Itérer à travers toutes les paires clé-valeur de la page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
			removeSuccess, removeError = pcall(function()
				hashMap:RemoveAsync(entry.key)
			end)

			if not removeSuccess then
				warn(removeError)
			end
		end
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			print("Suppression de toutes les données terminée.")
			break
		else
			print("----------")
			-- Avancer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end