Geheugenopslag hash map | Documentatie

Hash maps, vergelijkbaar met gesorteerde maps, stellen je in staat om gegevens in het geheugen op te slaan als sleutel-waarde paren. In tegenstelling tot gesorteerde maps behouden ze geen ordeningsgaranties. Deze gegevensstructuur is nuttig voor gevallen die eenvoudige gegevenscaching en snelle toegang vereisen, zoals gedeelde inventarissen, fysieke veilinghuizen, en meer. Hash maps beheren automatisch de partitionering van je gegevens en zijn zeer nuttig als je meer dan 1.000 sleutels hebt. Voor kleinere sleutelruimtes raden we gesorteerde maps aan.

Limieten

Hash maps hebben een limiet voor de sleutelgrootte van 128 tekens en een limiet voor de waarde van 32 KB.

Verder gebruiken hash maps dezelfde API-aanroep en geheugenquotum limieten als de andere gegevensstructuren voor geheugenopslag.

Verkrijg een hash map

Om een hash map te verkrijgen, roep je MemoryStoreService:GetHashMap() aan met een naam voor de hash map. De naam is globaal binnen het spel, zodat je dezelfde hash map op elk script kunt benaderen met deze naam.

Een Hash Map Verkrijgen

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Nadat je een hash map hebt verkregen, kun je een van de volgende functies aanroepen om gegevens erin te lezen of te schrijven:

Functie	Actie
MemoryStoreHashMap:SetAsync()	Voeg een nieuwe sleutel toe of overschrijf de waarde als de sleutel al bestaat.
MemoryStoreHashMap:GetAsync()	Lees een bepaalde sleutel.
MemoryStoreHashMap:ListItemsAsync()	Lijst items in een hash map.
MemoryStoreHashMap:UpdateAsync()	Werk de waarde van een sleutel bij nadat je deze uit een hash map hebt opgehaald.
MemoryStoreHashMap:RemoveAsync()	Verwijder een sleutel uit de hash map.

Voor uitgebreide documentatie over elke functie, zie MemoryStoreHashMap.

Alle functies die toegang hebben tot gegevensstructuren in geheugenopslag zijn asynchrone netwerkoproepen die af en toe kunnen mislukken. Je moet deze oproepen omhullen in pcall() om fouten op te vangen en af te handelen, zoals weergegeven in de codevoorbeelden.

Voeg gegevens toe of overschrijf deze

Om een nieuwe sleutel toe te voegen of de waarde van een sleutel in de hash map te overschrijven, roep je MemoryStoreHashMap:SetAsync() aan met de naam van de sleutel, de waarde en een vervaltijd in seconden. Het geheugen ruimt automatisch op zodra de sleutel vervalt. De maximale vervaltijd is 3.888.000 seconden (45 dagen).

Gegevens Toevoegen aan een Hash Map

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("Instellen geslaagd.")
end

Verkrijg gegevens

Je kunt ofwel een waarde ophalen die is gekoppeld aan een specifieke sleutel, of meerdere sleutel-waarde paren in de hash map ophalen.

Verkrijg gegevens met één sleutel

Om een waarde op te halen die is gekoppeld aan één sleutel uit de hash map, roep je MemoryStoreHashMap:GetAsync() aan met de naam van de sleutel.

Een Bepaalde Sleutel Verkrijgen uit een Hash Map

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("Instellen geslaagd.")
end

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

Verkrijg gegevens met meerdere sleutel-waarde paren

Om alle sleutel-waarde paren uit de hash map als één operatie op te halen, roep je MemoryStoreHashMap:ListItemsAsync() aan met de gewenste paginagrootte. Deze functie lijst alle bestaande sleutels op een gepagineerde manier. Bijvoorbeeld, de volgende codevoorbeelden haalt tot 32 items uit de hash map op.

Items Lijsten in een Hash Map

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Verkrijg lijst van items, 32 items per keer
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Verkrijg de huidige pagina
		local entries = pages:GetCurrentPage()
		-- Itereer door alle sleutel-waarde paren op de pagina
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Controleer of de laatste pagina is bereikt
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Ga naar de volgende pagina
			pages:AdvanceToNextPageAsync()
		end
	end
end

Werk gegevens bij

Om de waarde van een sleutel uit een hash map op te halen en deze bij te werken, roep je MemoryStoreHashMap:UpdateAsync() aan met de naam van de sleutel, een callbackfunctie om de sleutel bij te werken, en een vervaltijd in seconden.

Voor de meeste spellen kunnen meerdere servers tegelijkertijd dezelfde sleutel bijwerken en de waarde wijzigen. Aangezien UpdateAsync() altijd de laatste waarde wijzigt voordat deze wordt bijgewerkt, moet je deze gebruiken om de laatste waarde als invoer voor je callbackfunctie te lezen.

Bijvoorbeeld, de volgende codevoorbeelden werken het aantal middelen van een middel in een gedeelde inventaris bij. UpdateAsync() zorgt ervoor dat alle bijdragen van spelers in deze gedeelde inventaris terechtkomen, zelfs als deze bijdragen gelijktijdig worden gedaan. In deze functie wordt ook een maximaal aantal middelen van 500 afgedwongen.

Hulpbronnen Aantal Bijwerken voor een Middel in een Gedeelde Inventaris

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

			-- zorg ervoor dat we het maximale aantal middelen niet overschrijden
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

De latentie voor UpdateAsync() is vergelijkbaar met GetAsync() en SetAsync() tenzij er concurrentie is.

Wanneer er concurrentie optreedt, probeert het systeem automatisch de operatie opnieuw totdat een van deze drie dingen gebeurt: de operatie slaagt, de callbackfunctie retourneert nil, of het maximale aantal herhalingen is bereikt. Als het systeem het maximale aantal herhalingen bereikt, retourneert het een conflict.

Verwijder gegevens

Je kunt MemoryStoreHashMap:RemoveAsync() gebruiken voor zowel het verwijderen van één sleutel uit de hash map als het verwijderen van alle gegevens in een geheugenopslag hash map.

Verwijder een sleutel

Om een sleutel uit de hash map te verwijderen, roep je MemoryStoreHashMap:RemoveAsync() aan met een naam van de sleutel.

Verwijder een Sleutel uit een Hash Map

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("Instellen geslaagd.")
end

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

Verwijder alle gegevens

Om alle gegevens in een hash map te verwijderen, lijst je al je items met MemoryStoreHashMap:ListItemsAsync(), en verwijder je ze vervolgens met MemoryStoreHashMap:RemoveAsync().

Verwijder alle gegevens in een Hash Map

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Verkrijg lijst van items, 32 items per keer
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Verkrijg de huidige pagina
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Itereer door alle sleutel-waarde paren op de pagina
		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
		-- Controleer of de laatste pagina is bereikt
		if pages.IsFinished then
			print("Klaar met het verwijderen van alle gegevens.")
			break
		else
			print("----------")
			-- Ga naar de volgende pagina
			pages:AdvanceToNextPageAsync()
		end
	end
end