thzdaq-api 0.0.6b3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- thzdaq_api/__init__.py +1 -0
- thzdaq_api/analysis.py +62 -0
- thzdaq_api/approvals.py +87 -0
- thzdaq_api/assistant/agents.md +202 -0
- thzdaq_api/assistant/assistant.md +23 -0
- thzdaq_api/assistant/hints.md +15 -0
- thzdaq_api/atomic.py +79 -0
- thzdaq_api/catalog.py +131 -0
- thzdaq_api/console.py +70 -0
- thzdaq_api/custom.py +326 -0
- thzdaq_api/daemon.py +183 -0
- thzdaq_api/data.py +55 -0
- thzdaq_api/declare.py +193 -0
- thzdaq_api/declaring.py +125 -0
- thzdaq_api/devices.py +307 -0
- thzdaq_api/errors.py +47 -0
- thzdaq_api/events.py +224 -0
- thzdaq_api/examples/hot_cold.py +67 -0
- thzdaq_api/examples/hot_cold_grid.py +74 -0
- thzdaq_api/examples/iv_analysis.py +34 -0
- thzdaq_api/examples/map.py +42 -0
- thzdaq_api/examples/monitor.py +35 -0
- thzdaq_api/examples/raw_instrument.py +37 -0
- thzdaq_api/examples/sweep.py +38 -0
- thzdaq_api/examples.py +79 -0
- thzdaq_api/guides.py +61 -0
- thzdaq_api/host.py +494 -0
- thzdaq_api/interpreters.py +422 -0
- thzdaq_api/kernel.py +137 -0
- thzdaq_api/lab.py +562 -0
- thzdaq_api/lanes.py +170 -0
- thzdaq_api/leases.py +29 -0
- thzdaq_api/lock.py +65 -0
- thzdaq_api/measurement_file.py +459 -0
- thzdaq_api/measurements.py +433 -0
- thzdaq_api/operation.py +52 -0
- thzdaq_api/origins.py +86 -0
- thzdaq_api/present.py +376 -0
- thzdaq_api/procedures.py +124 -0
- thzdaq_api/raw.py +272 -0
- thzdaq_api/remote.py +267 -0
- thzdaq_api/rights.py +81 -0
- thzdaq_api/script.py +382 -0
- thzdaq_api/scripts.py +133 -0
- thzdaq_api/sessions.py +176 -0
- thzdaq_api/station.py +192 -0
- thzdaq_api/terminal.py +66 -0
- thzdaq_api/tools.py +275 -0
- thzdaq_api/transport.py +93 -0
- thzdaq_api/ui.py +152 -0
- thzdaq_api/windows.py +192 -0
- thzdaq_api/wire.py +35 -0
- thzdaq_api/workspace.py +239 -0
- thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
- thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
- thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
- thzdaq_api-0.0.6b3.dist-info/licenses/LICENSE +21 -0
thzdaq_api/lanes.py
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
"""Lanes: one thread and queue per key, an instrument in the daemon.
|
|
2
|
+
|
|
3
|
+
The jobs of one instrument run in order in its lane; instruments do not wait
|
|
4
|
+
for each other, so a slow or hung power meter does not hold the SIS bias.
|
|
5
|
+
Instruments sharing a connection (a Prologix) still take turns on its lock. A
|
|
6
|
+
client calls the daemon in lanes too: the calls about one device in order,
|
|
7
|
+
none waiting for a device that hangs.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import logging
|
|
11
|
+
import queue
|
|
12
|
+
import threading
|
|
13
|
+
import time
|
|
14
|
+
from typing import Any, Callable, Dict, List, Optional, Tuple
|
|
15
|
+
|
|
16
|
+
logger = logging.getLogger(__name__)
|
|
17
|
+
|
|
18
|
+
# Called with (result, error) in the lane's thread when a job ends
|
|
19
|
+
Deliver = Callable[[Any, Optional[BaseException]], None]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class LaneReset(Exception):
|
|
23
|
+
"""A job that waited in a lane given up by reset()."""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class _Lane:
|
|
27
|
+
def __init__(self, key: str):
|
|
28
|
+
self.queue: "queue.Queue" = queue.Queue()
|
|
29
|
+
self.started: Optional[float] = None
|
|
30
|
+
self.label: Optional[str] = None
|
|
31
|
+
name = f"lane {key}" if key else "lane"
|
|
32
|
+
self.thread = threading.Thread(target=self.loop, name=name, daemon=True)
|
|
33
|
+
self.thread.start()
|
|
34
|
+
|
|
35
|
+
def loop(self) -> None:
|
|
36
|
+
while True:
|
|
37
|
+
item = self.queue.get()
|
|
38
|
+
if item is None:
|
|
39
|
+
return
|
|
40
|
+
job, deliver, label = item
|
|
41
|
+
self.label = label
|
|
42
|
+
self.started = time.monotonic()
|
|
43
|
+
try:
|
|
44
|
+
result = job()
|
|
45
|
+
except Exception as e:
|
|
46
|
+
logger.exception(f"Device job failed{f' ({label})' if label else ''}")
|
|
47
|
+
deliver(None, e)
|
|
48
|
+
else:
|
|
49
|
+
deliver(result, None)
|
|
50
|
+
finally:
|
|
51
|
+
self.started = None
|
|
52
|
+
self.label = None
|
|
53
|
+
# What deliver holds (GUI callbacks hold widgets) must not die here:
|
|
54
|
+
# its last reference stays with whoever deliver handed it to
|
|
55
|
+
del item, job, deliver
|
|
56
|
+
result = None
|
|
57
|
+
|
|
58
|
+
def abandon(self, key: str) -> None:
|
|
59
|
+
"""Fail the jobs that wait; the one running ends here when it can."""
|
|
60
|
+
while True:
|
|
61
|
+
try:
|
|
62
|
+
item = self.queue.get_nowait()
|
|
63
|
+
except queue.Empty:
|
|
64
|
+
break
|
|
65
|
+
if item is not None:
|
|
66
|
+
_, deliver, _ = item
|
|
67
|
+
deliver(None, LaneReset(f"the queue of {key} was reset"))
|
|
68
|
+
self.queue.put(None) # the thread ends after the job it runs
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class Lanes:
|
|
72
|
+
def __init__(self):
|
|
73
|
+
self._lanes: Dict[str, _Lane] = {}
|
|
74
|
+
self._lock = threading.Lock()
|
|
75
|
+
self._lane("") # jobs without an instrument
|
|
76
|
+
|
|
77
|
+
def _lane(self, key: str) -> _Lane:
|
|
78
|
+
with self._lock:
|
|
79
|
+
lane = self._lanes.get(key)
|
|
80
|
+
if lane is None:
|
|
81
|
+
lane = self._lanes[key] = _Lane(key)
|
|
82
|
+
return lane
|
|
83
|
+
|
|
84
|
+
def submit(
|
|
85
|
+
self,
|
|
86
|
+
key: str,
|
|
87
|
+
job: Callable[[], Any],
|
|
88
|
+
deliver: Deliver,
|
|
89
|
+
label: Optional[str] = None,
|
|
90
|
+
) -> None:
|
|
91
|
+
"""key: the instrument whose lane the job joins; label: the device it
|
|
92
|
+
talks to, named when it does not answer."""
|
|
93
|
+
self._lane(key).queue.put((job, deliver, label))
|
|
94
|
+
|
|
95
|
+
def call(
|
|
96
|
+
self, key: str, job: Callable[[], Any], label: Optional[str] = None
|
|
97
|
+
) -> Any:
|
|
98
|
+
"""Run the job in its lane and wait for it; its error is raised here."""
|
|
99
|
+
done = threading.Event()
|
|
100
|
+
outcome: list = []
|
|
101
|
+
|
|
102
|
+
def deliver(result, error):
|
|
103
|
+
outcome.append((result, error))
|
|
104
|
+
done.set()
|
|
105
|
+
|
|
106
|
+
self.submit(key, job, deliver, label)
|
|
107
|
+
done.wait()
|
|
108
|
+
result, error = outcome[0]
|
|
109
|
+
if error is not None:
|
|
110
|
+
raise error
|
|
111
|
+
return result
|
|
112
|
+
|
|
113
|
+
def reset(self, key: str) -> bool:
|
|
114
|
+
"""A new lane for key: the old one, held by a job that hangs, is given
|
|
115
|
+
up. Returns whether key had a lane."""
|
|
116
|
+
with self._lock:
|
|
117
|
+
old = self._lanes.pop(key, None)
|
|
118
|
+
if old is None:
|
|
119
|
+
return False
|
|
120
|
+
old.abandon(key)
|
|
121
|
+
return True
|
|
122
|
+
|
|
123
|
+
def status(self) -> List[Tuple[str, int, Optional[str], float]]:
|
|
124
|
+
"""Each instrument's lane: (instrument, jobs waiting, the device the
|
|
125
|
+
running job talks to, seconds it has run)."""
|
|
126
|
+
now = time.monotonic()
|
|
127
|
+
found = []
|
|
128
|
+
for key, lane in list(self._lanes.items()):
|
|
129
|
+
if not key:
|
|
130
|
+
continue # jobs of no instrument
|
|
131
|
+
started, label = lane.started, lane.label # the lane changes meanwhile
|
|
132
|
+
busy = 0.0 if started is None else now - started
|
|
133
|
+
found.append((key, lane.queue.qsize(), label, busy))
|
|
134
|
+
return found
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def pending(self) -> int:
|
|
138
|
+
return sum(lane.queue.qsize() for lane in list(self._lanes.values()))
|
|
139
|
+
|
|
140
|
+
def _slowest(self) -> Tuple[Optional[float], Optional[str]]:
|
|
141
|
+
"""(start, label) of the longest job in progress; lanes change meanwhile."""
|
|
142
|
+
busy = []
|
|
143
|
+
for lane in list(self._lanes.values()):
|
|
144
|
+
started, label = lane.started, lane.label
|
|
145
|
+
if started is not None:
|
|
146
|
+
busy.append((started, label))
|
|
147
|
+
return min(busy, key=lambda item: item[0], default=(None, None))
|
|
148
|
+
|
|
149
|
+
def busy_for(self) -> float:
|
|
150
|
+
"""Seconds the longest job in progress has been running (0 when idle)."""
|
|
151
|
+
started, _ = self._slowest()
|
|
152
|
+
return 0.0 if started is None else time.monotonic() - started
|
|
153
|
+
|
|
154
|
+
@property
|
|
155
|
+
def current(self) -> Optional[str]:
|
|
156
|
+
"""Label of the longest job in progress."""
|
|
157
|
+
return self._slowest()[1]
|
|
158
|
+
|
|
159
|
+
@property
|
|
160
|
+
def started_at(self) -> Optional[float]:
|
|
161
|
+
"""When the longest job in progress started (monotonic), None when idle."""
|
|
162
|
+
return self._slowest()[0]
|
|
163
|
+
|
|
164
|
+
def stop(self, timeout: float = 2.0) -> None:
|
|
165
|
+
lanes = list(self._lanes.values())
|
|
166
|
+
for lane in lanes:
|
|
167
|
+
lane.queue.put(None)
|
|
168
|
+
deadline = time.monotonic() + timeout
|
|
169
|
+
for lane in lanes:
|
|
170
|
+
lane.thread.join(max(0.0, deadline - time.monotonic()))
|
thzdaq_api/leases.py
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Who uses a device now and how: the leases of running measurements.
|
|
2
|
+
|
|
3
|
+
read: only reads it; shared: sets it, others may too (a load, the LO);
|
|
4
|
+
exclusive: sweeps it, so another's change spoils its data. Only exclusive use
|
|
5
|
+
conflicts, and an explicit intent (share) goes on anyway; both measurements
|
|
6
|
+
record it.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from typing import Tuple
|
|
10
|
+
|
|
11
|
+
import msgspec
|
|
12
|
+
|
|
13
|
+
from thzdaq_api.operation import Operation
|
|
14
|
+
|
|
15
|
+
READ = "read"
|
|
16
|
+
SHARED = "shared"
|
|
17
|
+
EXCLUSIVE = "exclusive"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class LeaseInfo(msgspec.Struct, frozen=True):
|
|
21
|
+
device: str
|
|
22
|
+
mode: str # read, shared or exclusive
|
|
23
|
+
run: int # the measurement using it
|
|
24
|
+
title: str # of that measurement
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class ListLeases(Operation[Tuple[LeaseInfo, ...]]):
|
|
28
|
+
"""Devices in use by running measurements and how: read (only reads),
|
|
29
|
+
shared (sets it, others may too) or exclusive (sweeps it)."""
|
thzdaq_api/lock.py
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""A lock the operating system holds for a process on a file: it goes when the
|
|
2
|
+
process ends, however it ends, so a crashed daemon leaves no stale lock."""
|
|
3
|
+
|
|
4
|
+
import sys
|
|
5
|
+
import time
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import IO, Optional
|
|
8
|
+
|
|
9
|
+
# Taking a lock held by another process is retried this often until the timeout:
|
|
10
|
+
# the operating systems offer no timed wait on a file lock
|
|
11
|
+
RETRY_S = 0.05
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class FileLock:
|
|
15
|
+
def __init__(self, path: Path):
|
|
16
|
+
self.path = Path(path)
|
|
17
|
+
self._file: Optional[IO] = None
|
|
18
|
+
|
|
19
|
+
def acquire(self, timeout: float = 0.0) -> bool:
|
|
20
|
+
"""Take the lock, waiting up to timeout seconds; False if another holds it."""
|
|
21
|
+
self.path.parent.mkdir(parents=True, exist_ok=True)
|
|
22
|
+
file = open(self.path, "a+b")
|
|
23
|
+
deadline = time.monotonic() + timeout
|
|
24
|
+
while True:
|
|
25
|
+
try:
|
|
26
|
+
_lock(file)
|
|
27
|
+
except OSError:
|
|
28
|
+
if time.monotonic() >= deadline:
|
|
29
|
+
file.close()
|
|
30
|
+
return False
|
|
31
|
+
time.sleep(RETRY_S)
|
|
32
|
+
else:
|
|
33
|
+
self._file = file
|
|
34
|
+
return True
|
|
35
|
+
|
|
36
|
+
def release(self) -> None:
|
|
37
|
+
if self._file is not None:
|
|
38
|
+
_unlock(self._file)
|
|
39
|
+
self._file.close()
|
|
40
|
+
self._file = None
|
|
41
|
+
|
|
42
|
+
@property
|
|
43
|
+
def held(self) -> bool:
|
|
44
|
+
return self._file is not None
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
if sys.platform == "win32":
|
|
48
|
+
import msvcrt
|
|
49
|
+
|
|
50
|
+
def _lock(file: IO) -> None:
|
|
51
|
+
file.seek(0)
|
|
52
|
+
msvcrt.locking(file.fileno(), msvcrt.LK_NBLCK, 1)
|
|
53
|
+
|
|
54
|
+
def _unlock(file: IO) -> None:
|
|
55
|
+
file.seek(0)
|
|
56
|
+
msvcrt.locking(file.fileno(), msvcrt.LK_UNLCK, 1)
|
|
57
|
+
|
|
58
|
+
else:
|
|
59
|
+
import fcntl
|
|
60
|
+
|
|
61
|
+
def _lock(file: IO) -> None:
|
|
62
|
+
fcntl.flock(file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
63
|
+
|
|
64
|
+
def _unlock(file: IO) -> None:
|
|
65
|
+
fcntl.flock(file.fileno(), fcntl.LOCK_UN)
|