Geordende kaart van geheugenopslag

De geordende kaart gegevensstructuur van geheugenopslag stelt je in staat om frequente in-memory gegevens op te slaan als sleutel-waarde paren met een optionele sorteersleutel en een specifieke volgorde te behouden op basis van de sorteersleutels en sleutels. In tegenstelling tot wachtrijen bepaalt de volgorde waarin sleutels een kaart binnenkomen niet de volgorde van verwerking, waardoor geordende kaarten nuttig zijn voor het sorteren van gegevensorganisatie voor het implementeren van in-game entiteiten voor betrokkenheid, zoals ranglijsten en cross-server veilingen.

Limieten

Naast de limieten voor de grootte van gegevensstructuren, hebben geordende kaarten een limiet voor de sleutelgrootte van 128 tekens, een limiet voor de waarde-grootte van 32 KB en een limiet voor de sorteersleutelgrootte van 128 tekens.

Als je gegevens moet opslaan die deze limiet voor je spel overschrijden, kun je de sharding-techniek toepassen om ze te splitsen en te verdelen via sleutelprefix in meerdere gegevensstructuren. Sharding van geheugenopslag kan ook helpen om de schaalbaarheid van je systeem te verbeteren.

Verkrijg een geordende kaart

Om een geordende kaart te verkrijgen, roep je MemoryStoreService:GetSortedMap() aan met een naam die je wilt definiëren voor de kaart. De naam is globaal binnen het spel, zodat je dezelfde geordende kaart op elk script kunt openen met de naam.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Nadat je een geordende kaart hebt verkregen, kun je een van de volgende functies aanroepen:

Voeg gegevens toe of overschrijf deze

Om een nieuwe sleutel toe te voegen of de waarde of sorteersleutel van een sleutel in de geordende kaart te overschrijven, roep je MemoryStoreSortedMap:SetAsync() aan met de sleutel naam, de waarde, een vervaltijd in seconden en een optionele sorteersleutel. Het geheugen ruimt automatisch op zodra de sleutel vervalt. De maximale vervaltijd is 3.888.000 seconden (45 dagen). De sorteersleutel, indien opgegeven, moet een geldig nummer (geheel of drijvend punt) of een string zijn.

In de sorteervolgorde van je sleutels heeft een sorteersleutel voorrang boven een sleutel. Bijvoorbeeld, bij het sorteren in oplopende volgorde, worden numerieke sorteersleutels eerst gesorteerd, gevolgd door string sorteersleutels, gevolgd door items zonder sorteersleutel. Alle items met numerieke sorteersleutels worden gesorteerd op sorteersleutel; als de sorteersleutel voor twee items gelijk is, worden ze gesorteerd op sleutel. Evenzo worden alle items met string sorteersleutels gesorteerd op sorteersleutel; als de sorteersleutel voor twee items gelijk is, worden ze gesorteerd op sleutel. Alle items zonder sorteersleutel worden alleen gesorteerd op de sleutel.

Voorbeeld van enkele gegevens gesorteerd in oplopende volgorde -

{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}

Let op hoe player0 na alle sleutels met een sorteersleutel sorteert. player6 sorteert na alle sleutels met een numerieke sorteersleutel. player4 en player5 hebben dezelfde sorteersleutel, dus ze worden in oplopende volgorde op sleutel gesorteerd.

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

Verkrijg gegevens

Je kunt ofwel een gegevenswaarde en sorteersleutel ophalen die aan een specifieke sleutel zijn gekoppeld, of meerdere waarden en sorteersleutels voor sleutels binnen een bereik ophalen.

Verkrijg gegevens met één sleutel

Om een waarde en sorteersleutel op te halen die aan één sleutel uit de geordende kaart zijn gekoppeld, roep je MemoryStoreSortedMap:GetAsync() aan met de sleutel naam.

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

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

Verkrijg gegevens met meerdere sleutels

Om gegevens voor meerdere sleutels uit de geordende kaart als één operatie op te halen, roep je MemoryStoreSortedMap:GetRangeAsync() aan. Deze functie lijst standaard alle bestaande sleutels op, maar je kunt de boven- en ondergrenzen voor het sleutelbereik instellen. Bijvoorbeeld, de volgende codevoorbeeld haalt tot 20 items op, beginnend vanaf het begin van de geordende kaart, met sleutels groter dan of gelijk aan 10, sorteersleutels groter dan of gelijk aan 100 en sleutels kleiner dan of gelijk aan 50, sorteersleutels kleiner dan of gelijk aan 500.

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

-- Verkrijg tot 20 items beginnend vanaf het begin
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

Werk gegevens bij

Om de waarde en sorteersleutel van een sleutel uit een geordende kaart op te halen en deze bij te werken, roep je MemoryStoreSortedMap:UpdateAsync() aan met de sleutel naam, een callbackfunctie om de waarde en sorteersleutel voor deze sleutel bij te werken, en een vervaltijd in seconden. De maximale vervaltijd is 3.888.000 seconden (45 dagen).

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, het volgende codevoorbeeld werkt de score in een ranglijst voor een speler bij. De score wordt berekend als kills / deaths. UpdateAsync() zorgt ervoor dat de kills en deaths worden bijgewerkt voor de meest recente waarden, zelfs als meerdere game-servers tegelijkertijd hetzelfde item bijwerken. De kills en deaths van een speler zijn monotoon toenemende waarden en kunnen daarom alleen in waarde toenemen in een sessie.

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` is de sorteersleutel die wordt gebruikt om items in de kaart te sorteren
				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

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

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

Verwijder gegevens

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

Verwijder een sleutel

Om een sleutel uit de geordende kaart te verwijderen, roep je MemoryStoreSortedMap:RemoveAsync() aan met een sleutel naam.

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

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

Verwijder alle gegevens

Om geheugen in geordende kaarten te verwijderen, lijst je al je sleutels op met MemoryStoreSortedMap:GetRangeAsync(), en verwijder ze vervolgens met MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Initiële ondergrens van nil begint flush vanaf het eerste item
local exclusiveLowerBound = nil

while true do
	-- Verkrijg tot honderd items beginnend vanaf de huidige ondergrens
	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

		-- Als er een fout was bij het verwijderen van items, probeer het opnieuw met dezelfde exclusieve ondergrens
		if not removeSuccess then
			warn(removeError)
		-- Als het bereik minder dan honderd items is, is het einde van de kaart bereikt
		elseif #items < 100 then
			break
		else
			-- De laatst opgehaalde sleutel is de exclusieve ondergrens voor de volgende iteratie
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Verkrijg grootte

Om het aantal items in de geordende kaart te krijgen, roep je MemoryStoreSortedMap:GetSizeAsync() aan.

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

local size
local success, sizError = pcall(function()
	size = sortedMap:GetSizeAsync()
end)

if success then
	print(size)
else
	warn(sizeError)
end