MemoryStoreQueue
MemoryStoreQueue : Instance
Overview
MemoryStoreQueue is a priority-queue memory store shared by multiple servers in the same world. Use it when multiple servers need to divide up and process items, such as matchmaking queues or distributing work across servers.
It can only be retrieved through the MemoryStoreService:GetQueue() method and cannot be created with Instance.new().
This object can only be used in server Scripts, and calling it from a LocalScript raises an error.
Item Processing Flow
Add items to the queue with AddAsync. Items with higher priority come out first, and among items with the same priority, the one added first comes out first.
Read items with ReadAsync. Items that have been read are not deleted from the queue; they are hidden from other reads for the invisibility timeout specified in GetQueue().
When processing is finished, pass the read ID returned by ReadAsync to RemoveAsync to delete the items.
If RemoveAsync is not called before the invisibility timeout elapses, the items reappear in the queue. Items are not lost even if the server shuts down during processing.
Important Notes
Because the storage is volatile, data may be lost when the storage restarts.
The Async methods of this object yield the calling script until the result is received. A failed request raises an error, so wrapping calls in pcall is recommended.
Properties
Methods
AddAsync
Adds a value to the queue.
This method yields the calling script until the addition is complete. A failed addition raises an error.
Parameters
Value InValue
The value to add to the queue.
Must be 1 to 32,768 bytes when serialized.
Passing a table with circular references or a value of a type that cannot be stored raises an error.
Omitting it or passing nil raises an error.
Value InExpiration
The expiration time of the item (in seconds).
Must be between 0 and 3,888,000 seconds (45 days), and decimals can also be specified.
Expired items are removed from the queue.
There is no default value, so omitting it or passing nil raises an error.
number InPriority
(Optional) The priority of the item.
Higher values are read first, and among items with the same priority, the one added first is read first.
If omitted, it is 0.
Passing a non-finite value such as NaN or infinity raises an error.
Return
Value
There is no return value (nil).
Code Samples
GetSizeAsync
Returns the number of items in the queue.
By default, the count includes items that have been read by ReadAsync and are hidden. Expired items are excluded from the count.
This method yields the calling script until the result is received.
Important Notes
When InExcludeInvisible is set to true, a value larger than the actual count may be returned if expired items have not been cleaned up yet.
Parameters
boolean InExcludeInvisible
(Optional) Whether to exclude hidden items from the count.
If true, only items that can currently be read are counted.
If omitted, it is false, and hidden items are included in the count.
Return
Value
The number of items in the queue (number). It is 0 for a queue to which nothing has been added yet.
Code Samples
ReadAsync
Reads items from the queue in priority order.
Items that have been read are not deleted from the queue; they are hidden from other reads for the invisibility timeout specified in GetQueue(). When processing is finished, pass the returned read ID to RemoveAsync to delete the items.
If there are no items to read in the queue, it waits for up to InWaitTimeout, checking again at intervals of about 2 seconds.
This method yields the calling script until the result is received.
Parameters
number InCount
(Optional) The maximum number of items to read.
Must be between 1 and 100, and a value outside this range raises an error.
If omitted, it is 1.
boolean InAllOrNothing
(Optional) The behavior when InCount items cannot be filled.
If true, no items are read when InCount items cannot be read.
If omitted, it is false, and as many items as can be read are read.
number InWaitTimeout
(Optional) The maximum time (in seconds) to wait when there are no items to read.
If 0, it checks only once and returns immediately.
If negative, it keeps waiting until items become available.
If omitted, it is -1, and it keeps waiting.
Return
Tuple
Returns the items that were read together with a read ID.
The first value is an array of the values that were read.
The second value is the read ID (string) to pass to RemoveAsync.
If no items were read, both values are nil rather than an empty table.
Code Samples
RemoveAsync
Deletes items read by ReadAsync from the queue to signal that processing is complete.
Items read by a single ReadAsync call are deleted as one batch, and only some of them cannot be deleted. If some items could not be processed, do not call RemoveAsync; instead, wait for the invisibility timeout to elapse so the items return to the queue.
This method yields the calling script until the deletion is complete.
Important Notes
Calling it with a previous read ID after the invisibility timeout has elapsed does not delete the items, but it is treated as a success without an error. This is because another server may have read the same items in the meantime.
Calling it multiple times with the same read ID produces the same result.
Parameters
string InReadId
The read ID returned by ReadAsync as its second value.
Passing an empty string raises an error.
Return
Value
There is no return value (nil).
Code Samples
Events
Last updated