TqSdk Timers and Deadlines

Article TqSdk

Summary

This TqSdk guide explains how to run timed actions inside the main loop driven by wait_update, rather than pausing the program with a separate sleep loop. For actions tied to the trading session, it recommends checking the market timestamp in quote.datetime, which keeps timing aligned with exchange data rather than a potentially drifting local clock. Its example checks for a specified time near the close and then requests a target position of zero.

For bounded waits, the guide describes wait_update's deadline argument, which takes an absolute Unix timestamp, commonly computed by adding a duration to time.time(). It identifies uses such as allowing order or cancellation updates to arrive and limiting how long a stage can wait. The examples are usage guidance, not evidence about strategy performance. The guide also cautions that sleeping can stall data and background tasks, and that the update loop must continue after order actions; coroutine-based strategies should use update notifications consistently.

Key ideas

Drive scheduled actions from the main loop using wait_update so subscriptions and background tasks continue running.
Use quote.datetime when timing should follow exchange market time.
The deadline argument expects an absolute Unix timestamp rather than a duration by itself.
Continue calling wait_update after submitting or adjusting orders so updates can be processed.
For coroutine-based strategies, use update notifications instead of mixing synchronous and asynchronous waits.

Tags

Execution Futures Risk management

Full text

# timer


.. _timer:

定时器
=================================================

在 TqSdk 里，定时逻辑通常不是单独开一个 ``sleep`` 循环，而是和 :py:meth:`~tqsdk.TqApi.wait_update` 结合在同一个主循环里执行。这样可以保证订阅、下单、撤单以及后台任务仍然持续被驱动。

优先使用“行情时间”而不是本机时间
-------------------------------------------------

如果你的逻辑和交易时段、收盘前平仓、定时检查等场景有关，优先使用 ``quote.datetime`` 代表的行情时间::

    from datetime import datetime
    from tqsdk import TqApi, TqAuth, TargetPosTask

    api = TqApi(auth=TqAuth("快期账户", "账户密码"))
    quote = api.get_quote("SHFE.rb2610")
    target_pos = TargetPosTask(api, "SHFE.rb2610")
    close_hour, close_minute = 14, 50

    while True:
        api.wait_update()
        if api.is_changing(quote, "datetime"):
            now_time = datetime.strptime(quote.datetime, "%Y-%m-%d %H:%M:%S.%f")
            if now_time.hour == close_hour and now_time.minute >= close_minute:
                print("临近收盘，平仓")
                target_pos.set_target_volume(0)
                break

这种方式的好处是：你的定时判断和交易所时间保持一致，不依赖本机时钟是否漂移。

用 deadline 做“等待一段时间后继续”
-------------------------------------------------

:py:meth:`~tqsdk.TqApi.wait_update` 提供了 ``deadline`` 参数。它接收的是 ``time.time()`` 风格的 unix 时间戳，适合做“最多再等多久”的控制::

    import time
    from tqsdk import TqApi, TqAuth

    api = TqApi(auth=TqAuth("快期账户", "账户密码"))
    quote = api.get_quote("SHFE.rb2610")

    while True:
        api.wait_update()
        if api.is_changing(quote, "datetime"):
            print("收到一次关键更新，接下来最多再等 60 秒")
            deadline = time.time() + 60
            while api.wait_update(deadline=deadline):
                pass
            print("等待结束，继续执行后续逻辑")

这类写法适合：

* 收盘前平仓后再等待一小段时间，确认撤单和回报处理完毕
* 给某个阶段性任务一个最长等待时间，避免长时间阻塞
* 在同步主循环里做简单的“超时退出”控制

常见误区
-------------------------------------------------

* 不要在主循环里频繁使用 ``time.sleep()``, 否则会阻塞 ``wait_update``，数据和后台任务都会停下来
* ``deadline`` 是 unix 时间戳，不是“秒数”本身；通常写成 ``time.time() + 60``
* 如果你在定时逻辑里调用了 ``insert_order`` 或 ``TargetPosTask.set_target_volume``，后面仍然要继续调用 ``wait_update``，否则报单不会真正发出
* 如果策略已经采用协程任务，优先考虑 :py:meth:`~tqsdk.TqApi.register_update_notify`，不要把同步和异步等待方式混在一起

Shown in full with attribution under the source's licence. Licence: Apache-2.0

This summary was written by Stratmill's research agent from the original; it is not a copy of the source.

Scheduling Trading Logic with TqSdk Update Loops and Deadlines

Summary

Key ideas

Tags