ReadAsync

Yields

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts.

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

MemoryStoreQueue

Description:

Reads one or more items from the queue as a single atomic operation.

This method does not automatically delete the returned items from the queue but makes them invisible to other ReadAsync calls for the period of the invisibility timeout. The items must be explicitly removed from the queue with MemoryStoreQueue/RemoveAsync before the invisibility timeout expires. The invisibility timeout defaults to 30 seconds unless a different value was provided in MemoryStoreService/GetQueue.

Parameters

Name	Type	Default	Description
Name count	Type int	Default	Summary Number of items to read. The maximum allowed value of this parameter is 100.
Name allOrNothing	Type bool	Default false	Summary Controls the behavior of the method in the case the queue has fewer than `count` items: if set to false the method returns all available items; if set to true, it returns no items. The default value is false.
Name waitTimeout	Type double	Default -1	Summary The duration, in seconds, for which the method will wait if the required number of items is not immediately available in the queue. This parameter can be set to zero to indicate no wait. If this parameter is not provided or set to -1, the method will wait indefinitely.

Returns

Return Type	Summary
Return Type Tuple	Summary A tuple of two elements. The first element is an array of item values read from the queue. The second element is a string identifier that should be passed to `MemoryStoreQueue/RemoveAsync` to permanently remove these items from the queue.

Code Samples

Using a MemoryStoreQueue

The following code sample demonstrates using MemoryStoreQueue/ReadAsync and MemoryStoreQueue/RemoveAsync to reliably read, process, and remove items from a queue. While the processing code can be as complicated as necessary, in this example we simply set a flag in the corresponding datastore item; it guarantees that every item will eventually be processed even if some of the calls encounter errors or the game server crashes:

If ReadAsync() fails, no items are retrieved from the queue. An item will be picked up for processing during the next iteration of the loop.
If ReadAsync() succeeds but DataStoreService/UpdateAsync|ds:UpdateAsync fails, the item will stay invisible until the queue’s invisibility timeout expires, leading to the item becoming visible again to be returned in a future loop iteration.
Similarly, if RemoveAsync() fails, the item will become visible again in the future and will be processed again.

Note that depending on where the failure happens, it is possible that an item will be processed more than once and the processing code should account for that. It’s not a problem in this sample code since the end result is the same, even if ds:UpdateAsync is invoked multiple times.

			
				Using a MemoryStoreQueue
			
				Expected Output
			
				Expand
				
			-- obtain necessary services and instances
local UMS = game:GetService("MemoryStoreService")
local DSS = game:GetService(“DataStoreService”)
local queue = UMS:GetQueue("PlayerQueue")
local ds = DSS:GetDataStore(“PlayerStore”)

-- main processing loop
while true do
    pcall(function()
        -- wait for an item to process
        local items, id = queue:ReadAsync(1, false, 30)

        -- check if an item was retrieved
        if #items > 0 then
            -- mark the item as processed
            ds:UpdateAsync(items[0], function(data)
                data = data or {}
                data.processed = 1
                return data
            end)

            -- remove the item from the queue
            queue:RemoveAsync(id)
        end
    end)
end
		
				Copy Code
			
				Light Theme

ReadAsync

Parameters

count

allOrNothing

waitTimeout

Returns

Tuple

Code Samples

Using a MemoryStoreQueue