时间和时钟

Time and clocks

中文

每次调用 run() 都会关联一个时钟。

默认情况下，Trio 使用一个未指定的单调时钟，但可以通过将自定义时钟对象传递给 run() 来更改（例如用于测试）。

您不应假设 Trio 的内部时钟与您可以访问的任何其他时钟匹配，包括在其他进程或线程中同时调用 trio.run() 的时钟！

当前默认时钟实现为 time.perf_counter() 加上一个大的随机偏移量。这样做的目的是捕捉到那些不小心过早使用 time.perf_counter() 的代码，这有助于保持我们将来 更改时钟实现的选项，并且（更重要的是）确保您可以确信，像 trio.testing.MockClock 这样的自定义时钟将在您无法控制的第三方库中正常工作。

trio.current_time()

Returns the current time according to Trio's internal clock.

返回:

The current time.

返回类型:

float

抛出:

RuntimeError -- if not inside a call to trio.run().

await trio.sleep(seconds)

Pause execution of the current task for the given number of seconds.

参数:

seconds (float) -- The number of seconds to sleep. May be zero to insert a checkpoint without actually blocking.

抛出:

ValueError -- if seconds is negative or NaN.

返回类型:

None

await trio.sleep_until(deadline)

Pause execution of the current task until the given time.

The difference between sleep() and sleep_until() is that the former takes a relative time and the latter takes an absolute time according to Trio's internal clock (as returned by current_time()).

参数:

deadline (float) -- The time at which we should wake up again. May be in the past, in which case this function executes a checkpoint but does not block.

抛出:

ValueError -- if deadline is NaN.

返回类型:

None

await trio.sleep_forever()

Pause execution of the current task forever (or until cancelled).

Equivalent to calling await sleep(math.inf), except that if manually rescheduled this will raise a RuntimeError.

抛出:

RuntimeError -- if rescheduled

返回类型:

NoReturn

如果您是个疯狂的科学家，或者出于其他原因，觉得有必要直接控制 时间的流逝本身，那么您可以实现一个自定义的 Clock 类：

class trio.abc.Clock

基类：ABC

The interface for custom run loop clocks.

abstractmethod current_time()

Return the current time, according to this clock.

This is used to implement functions like trio.current_time() and trio.move_on_after().

返回:

The current time.

返回类型:

float

abstractmethod deadline_to_sleep_time(deadline)

Compute the real time until the given deadline.

This is called before we enter a system-specific wait function like select.select(), to get the timeout to pass.

For a clock using wall-time, this should be something like:

return deadline - self.current_time()

but of course it may be different if you're implementing some kind of virtual clock.

参数:

deadline (float) -- The absolute time of the next deadline, according to this clock.

返回:

The number of real seconds to sleep until the given deadline. May be math.inf.

返回类型:

float

abstractmethod start_clock()

Do any setup this clock might need.

Called at the beginning of the run.

返回类型:

None

英文

Every call to run() has an associated clock.

By default, Trio uses an unspecified monotonic clock, but this can be changed by passing a custom clock object to run() (e.g. for testing).

You should not assume that Trio's internal clock matches any other clock you have access to, including the clocks of simultaneous calls to trio.run() happening in other processes or threads!

The default clock is currently implemented as time.perf_counter() plus a large random offset. The idea here is to catch code that accidentally uses time.perf_counter() early, which should help keep our options open for changing the clock implementation later, and (more importantly) make sure you can be confident that custom clocks like trio.testing.MockClock will work with third-party libraries you don't control.

trio.current_time()

Returns the current time according to Trio's internal clock.

返回:

The current time.

返回类型:

float

抛出:

RuntimeError -- if not inside a call to trio.run().

await trio.sleep(seconds)

Pause execution of the current task for the given number of seconds.

参数:

seconds (float) -- The number of seconds to sleep. May be zero to insert a checkpoint without actually blocking.

抛出:

ValueError -- if seconds is negative or NaN.

返回类型:

None

await trio.sleep_until(deadline)

Pause execution of the current task until the given time.

The difference between sleep() and sleep_until() is that the former takes a relative time and the latter takes an absolute time according to Trio's internal clock (as returned by current_time()).

参数:

deadline (float) -- The time at which we should wake up again. May be in the past, in which case this function executes a checkpoint but does not block.

抛出:

ValueError -- if deadline is NaN.

返回类型:

None

await trio.sleep_forever()

Pause execution of the current task forever (or until cancelled).

Equivalent to calling await sleep(math.inf), except that if manually rescheduled this will raise a RuntimeError.

抛出:

RuntimeError -- if rescheduled

返回类型:

NoReturn

If you're a mad scientist or otherwise feel the need to take direct control over the PASSAGE OF TIME ITSELF, then you can implement a custom Clock class:

class trio.abc.Clock

基类：ABC

The interface for custom run loop clocks.

abstractmethod current_time()

Return the current time, according to this clock.

This is used to implement functions like trio.current_time() and trio.move_on_after().

返回:

The current time.

返回类型:

float

abstractmethod deadline_to_sleep_time(deadline)

Compute the real time until the given deadline.

This is called before we enter a system-specific wait function like select.select(), to get the timeout to pass.

For a clock using wall-time, this should be something like:

return deadline - self.current_time()

but of course it may be different if you're implementing some kind of virtual clock.

参数:

deadline (float) -- The absolute time of the next deadline, according to this clock.

返回:

The number of real seconds to sleep until the given deadline. May be math.inf.

返回类型:

float

abstractmethod start_clock()

Do any setup this clock might need.

Called at the beginning of the run.

返回类型:

None