dbzero.async_wait()

async def async_wait(prefix_name: str, state_num: int)

The async_wait method provides a way to pause an asyncio coroutine until a specific data prefix reaches a target state number. Each time data is modified and committed within a prefix, its internal state number is incremented. This method is perfect for building reactive systems or synchronizing tasks that depend on data updates from other parts of your application, or even from different processes.

If the prefix's current state number is already greater than or equal to the target state_num, the await completes immediately.

Parameters

• prefix_name (str): The name of the prefix you want to monitor.
• state_num (int): The non-negative state number to wait for. The coroutine will resume once the prefix's current state is greater than or equal to this number.

Returns

An awaitable object (asyncio.Future). Awaiting this future blocks the coroutine until the condition is met. It does not return any value upon completion.

Examples

Waiting for the Next State Change

You can use async_wait to wait for the very next transaction to be committed in a prefix. This is useful when one part of your application needs to react to changes made by another.

import asyncio
 
# Get the current state number of the default prefix
current_state = db0.get_state_num("default")
 
print("Waiting for the next commit...")
 
# Create a task to wait for the state number to increment
wait_task = asyncio.create_task(
    db0.async_wait("default", current_state + 1)
)
 
# In another part of your code, make and commit a change
obj = MyMemoClass(value="initial")
obj.value = "updated" # This mutation will increment the state number on commit
# dbzero automatically commits the change
 
# The wait_task will now complete
await wait_task
print("State change detected!")

Synchronizing with an External Process

A powerful use case is coordinating between multiple processes. One process can wait for another to complete a specific number of transactions before proceeding.

# In your main async reader process:
prefix_name = "shared_data"
db0.open(prefix_name, "r")
 
print("Waiting for 5 transactions from the writer process...")
# Get the current state and wait for it to be incremented 5 times
start_state = db0.get_state_num(prefix_name)
await db0.async_wait(prefix_name, start_state + 5)
 
print("Done! 5 transactions were committed.")
 
# The writer_process (running separately) would look like this:
#
# def writer_process(prefix_name):
#     db0.init(...)
#     db0.open(prefix_name, "rw")
#     for i in range(5):
#         obj = DataPoint(i)
#         db0.commit() # Each commit increments the state number
#         time.sleep(0.1)