Mapa Armazenamento de Memória Sorted

A estrutura de dados ordenar mapa do memória armazenamento permite que você armazene dados de frequência em memória como pares de valor-chave com uma chave de classificação opcional e mantenha uma ordem específica com base nas chaves e nas chaves. Ao contrário das filas, a ordem das chaves entrando em um mapa não determina a ordem de processamento, tornando os mapas sortidos

Limites

Além dos limites de tamanho da estrutura de dados , os mapas sortidos têm um limite de tamanho da chave de 128 caracteres, um limite de tamanho do valor de 32 KB e um limite de tamanho da chave de 128 caracteres.

Se você precisar armazenar dados que excedem esse limite para sua experiência, você pode adotar a técnica de sharding para dividi-los e distribuí-los através de prefixo de chave em várias estruturas de dados. Sharding memory stores também pode ajudar a melhorar a escalabilidade do seu sistema.

Obtendo um Mapa Classificado

Para obter um mapa ordenado, chame MemoryStoreService:GetSortedMap() com um nome que você deseja definir para o mapa. O nome é global dentro da experiência, para que você possa acessar o mesmo mapa ordenado em qualquer script usando o nome.

Obtendo um Mapa Classificado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Depois de obter um mapa classificado, chame qualquer uma das seguintes funções para ler ou escrever dados nele:

Adicionando ou Substituindo Dados

Para adicionar uma nova chave ou sobrescrever o valor ou ordem da chave em um mapa sortido, chame MemoryStoreSortedMap:SetAsync() com o nome da chave, seu valor, um tempo de expiração em segundos e

Na ordem de classificação das suas chaves, uma chave de classificação toma precedência sobre uma chave. Por exemplo, quando classificar em ordem crescente, as chaves de classificação numéricas sortem primeiro, seguido por chaves de classificação de texto, seguido por itens sem chave de classificação. Todos os itens com chaves de classificação numéricas são classificados por ch

Exemplo de alguns dados classificados em ordem crescente -

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

Observe como player0 classifica depois de todas as chaves com uma chave de classificação. player6 classifica depois de todas as chaves com uma chave de classificação numérica. player4 e 1> player51> têm a mesma chave de classificação, então eles são classificados em ordem crescente por chave.

Adicionando Dados a um Mapa Classificado
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

Obtendo Dados

Você pode obter um valor de dado e classificar a chave associada a uma chave específica ou obter vários valores e classificar as chaves dentro de um alcance.

Obtendo Dados com uma Chave

Para obter um valor e classificar a chave associada a um key da mapa排序, chame MemoryStoreSortedMap:GetAsync() com o key nome .

Obtendo uma Chave Especial de um Mapa Classificado
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

Obtendo Dados com Várias Chaves

Para obter dados para várias chaves do mapa sortido como uma única operação, chame MemoryStoreSortedMap:GetRangeAsync() . Essa função lista todos os valores atuais por padrão, mas

Obtendo uma Gama de Chaves a partir Mapa Ordenado
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

-- Obtenha até 20 itens começando do início
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

Atualizando Dados

Para recuperar o valor e classificar a chave de uma chave a partir de um mapa ordenado e atualizá-la, chame MemoryStoreSortedMap:UpdateAsync() com a chave nome , uma função de chamada para atualizar o valor e classificar a chave para esta chave, e um 1> tempo de expiração1> em segundos.

Para a maioria das experiências, vários servidores podem atualizar a mesma chave simultaneamente e alterar o valor. Como UpdateAsync() sempre modifica o valor mais recente antes de atualizar, você deve usá-lo para ler o valor mais recente como entrada para sua função de chamada.

Por exemplo, o seguinte código de exemplo atualiza a pontuação em uma tabela de classificação para um jogador em um jogo. A pontuação é calculada como mortes / mortes. UpdateAsync() garante que as mortes e mortes sejam atualizadas para os valores mais recentes, mesmo que vários servidores de jogos atualizem o mesmo item simultaneamente. Um jogador's mortes

Atualizando a pontuação na tabela de classificação para um jogador em um mapa ordenado
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` é a chave de classificação usada para classificar itens no mapa
				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

A latência para UpdateAsync() é semelhante à GetAsync() e SetAsync() a menos que haja contenção.

Quando ocorre contenção, o sistema automaticamente tenta novamente a operação até que um desses três aconteça: a operação é bem-sucedida, a função de chamada retorna nil ou o número máximo de retries é atingido. Se o sistema atingir o número máximo de retries, ele retorna um conflito.

Removendo Dados

Você pode usar MemoryStoreSortedMap:RemoveAsync() para ambas as remoções de uma chave do mapa sortido e para todas as remoções de dados em um armazenamento de memória sortido.

Removendo uma Chave

Para remover uma chave do mapa ordenado, chame MemoryStoreSortedMap:RemoveAsync() com uma chave nome .

Remover uma Chave de um Mapa Ordenado
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

Excluindo Todos os Dados

Para excluir memória em mapas classificados, liste todas as suas chaves com MemoryStoreSortedMap:GetRangeAsync() , então remova-as com MemoryStoreSortedMap:RemoveAsync() .

Excluir Memória em um Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- A inicial inferior do zero começa a fluir a partir do primeiro item
local exclusiveLowerBound = nil

while true do
	-- Obtenha até 100 itens a partir do limite inferior atual
	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

		-- Se houve um erro ao remover itens, tente novamente com o mesmo limite inferior exclusivo
		if not removeSuccess then
			warn(removeError)
		-- Se a distância for menor que cem itens, o fim do mapa é atingido
		elseif #items < 100 then
			break
		else
			-- A última chave recuperada é a chave exclusiva para a próxima iteração
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end