You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/asking_questions.rst
+140-10
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,27 @@
4
4
Asking services questions
5
5
=========================
6
6
7
-
How to ask a question
8
-
=====================
7
+
What is a question?
8
+
===================
9
+
A question is a set of data (input values and/or an input manifest) sent to a child for processing/analysis. Questions
10
+
can be:
11
+
12
+
- **Synchronous ("ask-and-wait"):** A question whose answer is waited for in real time
13
+
14
+
- **Asynchronous ("fire-and-forget"):** A question whose answer is not waited for and is instead retrieved later. There
15
+
are two types:
16
+
17
+
- **Regular:** Responses to these questions are automatically stored in an event store where they can be :ref:`retrieved using the Octue SDK <retrieving_asynchronous_answers>`
18
+
19
+
- **Push endpoint:** Responses to these questions are pushed to an HTTP endpoint for asynchronous handling using Octue's
20
+
`django-twined <https://django-twined.readthedocs.io/en/latest/>`_ or custom logic in your own webserver.
21
+
9
22
Questions are always asked to a *revision* of a service. You can ask a service a question if you have its
10
-
:ref:`SRUID <sruid_definition>`, project name, and the necessary permissions. The question is formed of input values
11
-
and/or an input manifest.
23
+
:ref:`SRUID <sruid_definition>`, project name, and the necessary permissions.
24
+
25
+
26
+
Asking a question
27
+
=================
12
28
13
29
.. code-block:: python
14
30
@@ -47,19 +63,133 @@ You can also set the following options when you call :mod:`Child.ask <octue.reso
47
63
- ``subscribe_to_logs`` - if true, the child will forward its logs to you
48
64
- ``allow_local_files`` - if true, local files/datasets are allowed in any input manifest you supply
49
65
- ``handle_monitor_message`` - if provided a function, it will be called on any monitor messages from the child
50
-
- ``record_messages_to`` – if given a path to a JSON file, messages received from the parent while it processes the question are saved to it
66
+
- ``record_events`` – if ``True``, events received from the parent while it processes the question are saved to the ``Child.received_events`` property
51
67
- ``save_diagnostics`` – must be one of {"SAVE_DIAGNOSTICS_OFF", "SAVE_DIAGNOSTICS_ON_CRASH", "SAVE_DIAGNOSTICS_ON"}; if turned on, allow the input values and manifest (and its datasets) to be saved by the child either all the time or just if the analysis fails
52
68
- ``question_uuid`` - if provided, the question will use this UUID instead of a generated one
69
+
- ``push_endpoint`` - if provided, the result and other events produced during the processing of the question will be pushed to this HTTP endpoint (a URL)
70
+
- ``asynchronous`` - if ``True``, don't wait for an answer to the question (the result and other events can be :ref:`retrieved from the event store later <retrieving_asynchronous_answers>`)
53
71
- ``timeout`` - how long in seconds to wait for an answer (``None`` by default - i.e. don't time out)
54
72
73
+
Exceptions raised by a child
74
+
----------------------------
55
75
If a child raises an exception while processing your question, the exception will always be forwarded and re-raised in
56
76
your local service or python session. You can handle exceptions in whatever way you like.
57
77
58
-
If setting a timeout, bear in mind that the question has to reach the child, the child has to run its analysis on
59
-
the inputs sent to it (this most likely corresponds to the dominant part of the wait time), and the answer has to be
60
-
sent back to the parent. If you're not sure how long a particular analysis might take, it's best to set the timeout to
61
-
``None`` initially or ask the owner/maintainer of the child for an estimate.
78
+
Timeouts
79
+
--------
80
+
If setting a timeout, bear in mind that the question has to reach the child, the child has to run its analysis on the
81
+
inputs sent to it (this will most likely make up the dominant part of the wait time), and the answer has to be sent back
82
+
to the parent. If you're not sure how long a particular analysis might take, it's best to set the timeout to ``None``
83
+
initially or ask the owner/maintainer of the child for an estimate.
84
+
85
+
86
+
.. _retrieving_asynchronous_answers:
87
+
88
+
Retrieving answers to asynchronous questions
89
+
============================================
90
+
To retrieve results and other events from the processing of a question later, make sure you have the permissions to
91
+
access the event store and run:
92
+
93
+
.. code-block:: python
94
+
95
+
from octue.cloud.pub_sub.bigquery import get_events
0 commit comments