diff --git a/docs/source/history.rst b/docs/source/history.rst index 3c460e5763..5866faf62a 100644 --- a/docs/source/history.rst +++ b/docs/source/history.rst @@ -100,6 +100,8 @@ https://github.com/python-trio/trio/issues/314 - :class:`~trio.hazmat.Error` - :class:`~trio.hazmat.Value` - :func:`~trio.hazmat.current_task` + - :func:`~trio.hazmat.current_clock` + - :func:`~trio.hazmat.current_statistics` deprecate most of the task and nursery APIs diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst index 56ea434743..6cac152b33 100644 --- a/docs/source/reference-core.rst +++ b/docs/source/reference-core.rst @@ -228,11 +228,6 @@ custom :class:`~trio.abc.Clock` class: .. autoclass:: trio.abc.Clock :members: -You can also fetch a reference to the current clock, which might be -useful if you're using a custom clock class: - -.. autofunction:: current_clock - .. _cancellation: @@ -1534,69 +1529,6 @@ messages between the thread and a trio task:: trio.run(main) -.. _instrumentation: - -Debugging and instrumentation ------------------------------ - -Trio tries hard to provide useful hooks for debugging and -instrumentation. Some are documented above (the nursery introspection -attributes, :meth:`Queue.statistics`, etc.). Here are some more: - - -Global statistics -~~~~~~~~~~~~~~~~~ - -.. autofunction:: current_statistics - - -Instrument API -~~~~~~~~~~~~~~ - -The instrument API provides a standard way to add custom -instrumentation to the run loop. Want to make a histogram of -scheduling latencies, log a stack trace of any task that blocks the -run loop for >50 ms, or measure what percentage of your process's -running time is spent waiting for I/O? This is the place. - -The general idea is that at any given moment, :func:`trio.run` -maintains a set of "instruments", which are objects that implement the -:class:`trio.abc.Instrument` interface. When an interesting event -happens, it loops over these instruments and notifies them by calling -an appropriate method. The tutorial has :ref:`a simple example of -using this for tracing `. - -Since this hooks into trio at a rather low level, you do have to be -somewhat careful. The callbacks are run synchronously, and in many -cases if they error out then there isn't any plausible way to -propagate this exception (for instance, we might be deep in the guts -of the exception propagation machinery...). Therefore our `current -strategy `__ for -handling exceptions raised by instruments is to (a) dump a stack trace -to stderr and (b) disable the offending instrument. - -You can register an initial list of instruments by passing them to -:func:`trio.run`. :func:`add_instrument` and -:func:`remove_instrument` let you add and remove instruments at -runtime. There's also :func:`current_instruments`, which is deprecated -and will be removed soon. - -.. autofunction:: add_instrument - -.. autofunction:: remove_instrument - -.. autofunction:: current_instruments - -And here's the instrument API: - -.. autoclass:: trio.abc.Instrument - :members: - -The tutorial has a :ref:`fully-worked example -` of defining a custom instrument to log -trio's internal scheduling decisions. - - Exceptions and warnings ----------------------- diff --git a/docs/source/reference-hazmat.rst b/docs/source/reference-hazmat.rst index 565e2eacd9..8caa2f06a7 100644 --- a/docs/source/reference-hazmat.rst +++ b/docs/source/reference-hazmat.rst @@ -39,6 +39,73 @@ carefully: using this module makes it your responsibility to handle the nasty cases and expose a friendly Trio-style API to your users. +Debugging and instrumentation +============================= + +Trio tries hard to provide useful hooks for debugging and +instrumentation. Some are documented above (the nursery introspection +attributes, :meth:`trio.Queue.statistics`, etc.). Here are some more. + + +Global statistics +----------------- + +.. autofunction:: current_statistics + + +The current clock +----------------- + +.. autofunction:: current_clock + + +.. _instrumentation: + +Instrument API +-------------- + +The instrument API provides a standard way to add custom +instrumentation to the run loop. Want to make a histogram of +scheduling latencies, log a stack trace of any task that blocks the +run loop for >50 ms, or measure what percentage of your process's +running time is spent waiting for I/O? This is the place. + +The general idea is that at any given moment, :func:`trio.run` +maintains a set of "instruments", which are objects that implement the +:class:`trio.abc.Instrument` interface. When an interesting event +happens, it loops over these instruments and notifies them by calling +an appropriate method. The tutorial has :ref:`a simple example of +using this for tracing `. + +Since this hooks into trio at a rather low level, you do have to be +somewhat careful. The callbacks are run synchronously, and in many +cases if they error out then there isn't any plausible way to +propagate this exception (for instance, we might be deep in the guts +of the exception propagation machinery...). Therefore our `current +strategy `__ for +handling exceptions raised by instruments is to (a) dump a stack trace +to stderr and (b) disable the offending instrument. + +You can register an initial list of instruments by passing them to +:func:`trio.run`. :func:`add_instrument` and +:func:`remove_instrument` let you add and remove instruments at +runtime. + +.. autofunction:: add_instrument + +.. autofunction:: remove_instrument + +And here's the interface to implement if you want to build your own +:class:`~trio.abc.Instrument`: + +.. autoclass:: trio.abc.Instrument + :members: + +The tutorial has a :ref:`fully-worked example +` of defining a custom instrument to log +trio's internal scheduling decisions. + + Low-level I/O primitives ========================