Skip to content

Commit d5d0091

Browse files
shakfushakfu
committed
rename zthread to ztp
1 parent 55f35a7 commit d5d0091

35 files changed

+154
-111
lines changed

‎.gitignore

-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ workbook.leo
2121
.vscode
2222
.venv
2323
__pycache__
24-
archive
2524
build
2625
CMakeFiles
2726
env.sh

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
1717

1818
## [0.3.x]
1919

20+
- Renamed `zthread` to `ztp` to emphasize the use of zeromq + threads + python
21+
2022
- Building `py` and `pyjs` via `make` doesn't require `cython` to be installed.
2123

2224
- Restructured `CMakeLists.txt` to improve organization and readability:

‎CMakeLists.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ list(APPEND BUILD_TARGETS pktpy pktpy2)
8787
endif()
8888

8989
if(BUILD_NET_EXTERNALS)
90-
list(APPEND BUILD_TARGETS zedit zpy zthread jmx)
90+
list(APPEND BUILD_TARGETS zedit zpy ztp jmx)
9191
endif()
9292

9393
set(THIRDPARTY_EXTERNALS shell jit.fill2 jit.foo)

‎Makefile

+2-2
Original file line numberDiff line numberDiff line change
@@ -299,7 +299,7 @@ beeware-ext: clean-externals
299299
# -----------------------------------------------------------------------
300300
# experimental python3 externals
301301

302-
.PHONY: py pyjs cobra jmx zthread shell \
302+
.PHONY: py pyjs cobra jmx ztp shell \
303303
mamba mamba-static mamba-shared \
304304
mamba-framework mamba-framework-pkg \
305305
krait krait-static krait-shared \
@@ -326,7 +326,7 @@ jmx: clean-externals
326326
zpy: clean-externals
327327
$(call build-target,$@,local)
328328

329-
zthread: clean-externals
329+
ztp: clean-externals
330330
$(call build-target,$@,local)
331331

332332
shell:

‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,9 @@ The two pocketpy variants can be built with the cmake option, `-DBUILD_POCKETPY_
5252

5353
name | sdk | lang | description
5454
:--------- | :--------- | :----: | :---------------------------------------------------
55+
[ztp] | max-sdk | c | non-blocking communications with zeromq + threads + spawned python
5556
[jmx] | max-sdk | c | explore how to embed a [jupyter client](https://jupyter-client.readthedocs.io/en/stable/messaging.html) or [kernel](https://github.com/jupyter-xeus/xeus-python) in an external
5657
[zpy] | max-sdk | c | uses [zeromq](https://zeromq.org) for 2way-comms with an external python process
57-
[zthread] | max-sdk | c | exploration of zeromq and Max threads
5858

5959
Note: networking (zmq-based) externals are not enabled by default since they require zeromq libraries to be installed. To build them use the `-DBUILD_NETWORKING_EXTERNALS=ON` option with cmake or just `make net`
6060

@@ -258,4 +258,4 @@ Thanks to Greg Neagle for zeroing in on the relocatability problem and sharing h
258258
[zedit]: https://github.com/shakfu/py-js/tree/main/source/projects/zedit
259259
[mpy]: https://github.com/shakfu/py-js/tree/main/source/projects/mpy
260260
[jmx]: https://github.com/shakfu/py-js/tree/main/source/projects/jmx
261-
[zthread]: https://github.com/shakfu/py-js/tree/main/source/projects/zthread
261+
[ztp]: https://github.com/shakfu/py-js/tree/main/source/projects/ztp

‎TODO.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
# TODO
22

3-
- [ ] archive `zpy`, rename `zthread` to `ztpy` for 'zeromq-threaded-python', enable additional build variants.
43

5-
- [ ] `krait` and `cobra` to swap names
4+
- [ ] archive `zpy`, which is not so useful now.
65

7-
- [ ] Alternatively, use [buildpy](https://github.com/shakfu/buildpy) and
8-
[xcodegen](https://github.com/yonaskolb/XcodeGen) to build relocatable
6+
- [x] rename `zthread` to `ztp` for 'zeromq-threaded-python', enable additional build variants.
7+
8+
- [ ] `krait` and `cobra` to swap names
9+
10+
- [ ] Alternatively, use [buildpy](https://github.com/shakfu/buildpy) and [xcodegen](https://github.com/yonaskolb/XcodeGen) to build relocatable
911
python builds, generate xccongfig and xcode projects
1012

1113
- [ ] Try pyodide in the browser to communicate with Max via the external /

‎examples/servers/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# servers
22

3-
These are python files which are meant be run as a separate process by the `zthread` external.
3+
These are python files which are meant be run as a separate process by the `ztp` external.
44

55
- `pyserver.py`: provides python interpreter service

‎examples/servers/pyserver.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ def py_eval(code: str) -> Optional[Any]:
9696

9797

9898
def serve():
99-
log = logging.getLogger("zthread")
99+
log = logging.getLogger("ztp")
100100
log.info("server starting...")
101101

102102
with zmq.Context() as ctx:
@@ -111,7 +111,7 @@ def serve():
111111

112112
msg = message.decode()
113113

114-
if msg == 'ZTHREAD_EXIT':
114+
if msg == 'ZTP_EXIT':
115115
time.sleep(0.2)
116116
socket.send_string("closing connection")
117117
time.sleep(0.2)

‎help/zthread.maxhelp ‎help/ztp.maxhelp

+2-2
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@
288288
"numoutlets" : 1,
289289
"outlettype" : [ "" ],
290290
"patching_rect" : [ 235.0, 168.0, 348.0, 21.0 ],
291-
"text" : "zthread @python /opt/homebrew/bin/python3 @server pyserver.py"
291+
"text" : "ztp @python /opt/homebrew/bin/python3 @server pyserver.py"
292292
}
293293

294294
}
@@ -426,7 +426,7 @@
426426
],
427427
"originid" : "pat-4",
428428
"dependency_cache" : [ {
429-
"name" : "zthread.mxo",
429+
"name" : "ztp.mxo",
430430
"type" : "iLaX"
431431
}
432432
],

‎patchers/tests/test_zthread/test_zthread_shell.maxpat ‎patchers/tests/test_ztp/test_ztp_shell.maxpat

+2-2
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,7 @@
263263
"numoutlets" : 1,
264264
"outlettype" : [ "" ],
265265
"patching_rect" : [ 235.0, 168.0, 76.0, 21.0 ],
266-
"text" : "zthread"
266+
"text" : "ztp"
267267
}
268268

269269
}
@@ -387,7 +387,7 @@
387387
],
388388
"originid" : "pat-4",
389389
"dependency_cache" : [ {
390-
"name" : "zthread.mxo",
390+
"name" : "ztp.mxo",
391391
"type" : "iLaX"
392392
}
393393
],

‎source/docs/_book/Python3-Externals-for-Max-MSP.pdf

1 KB
Binary file not shown.

‎source/docs/_quarto.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ book:
3939
chapters:
4040
- src/externals/zedit.qmd
4141
- src/externals/zpy.qmd
42-
- src/externals/zthread.qmd
42+
- src/externals/ztp.qmd
4343
- src/externals/jmx.qmd
4444

4545
# - part: "Builder"

‎source/docs/src/externals/zthread.qmd

-11
This file was deleted.

‎source/docs/src/externals/ztp.qmd

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "ztp: the zeromq + threads + python Max external"
3+
---
4+
5+
```text
6+
┌─────────────────────────────────────────────────┐
7+
│┌───────────┐ ┌───────────┐│
8+
││ │ │python code││
9+
││ client │◀────────zeromq───────▶│ server ││
10+
││ │ │ (spawned) ││
11+
│└───────────┘ └───────────┘│
12+
│ ztp external │
13+
└─────────────────────────────────────────────────┘
14+
```
15+
16+
The `ztp` external (the name refers to python, threads and zeromq) uses `zmq` with threading for non-blocking communication with a spawned python code interpretation server which evaluates and executes python code and sends back the result.
17+
18+
The combination of threads, zeromq and remote process mgmt of the spawned server make this much more usable than `zpy`, an earlier effort which lacked threads and which suffered from blocking during communication with the server.
19+
20+
## Requires
21+
22+
```bash
23+
brew install zmq
24+
```
25+
26+
## Learnings
27+
28+
- This works: one thread per zmq socket as per the zmq rules.
29+
30+
-

‎source/docs/src/overview.qmd

+3-3
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,9 @@ The two pocketpy variants can be built with the cmake option, `-DBUILD_POCKETPY_
5454

5555
name | sdk | lang | description
5656
:--------- | :--------- | :----: | :---------------------------------------------------
57+
[ztp] | max-sdk | c | non-blocking communications with zeromq + threads + spawned python
5758
[jmx] | max-sdk | c | explore how to embed a [jupyter client](https://jupyter-client.readthedocs.io/en/stable/messaging.html) or [kernel](https://github.com/jupyter-xeus/xeus-python) in an external
5859
[zpy] | max-sdk | c | uses [zeromq](https://zeromq.org) for 2way-comms with an external python process
59-
[zthread] | max-sdk | c | exploration of zeromq and Max threads
6060

6161
Note: networking (zmq-based) externals are not enabled by default since they require zeromq libraries to be installed. To build them use the `-DBUILD_NETWORKING_EXTERNALS=ON` option with cmake or just `make net`
6262

@@ -112,7 +112,7 @@ If you'd rather build them or any of the other externals yourself then the proce
112112

113113
[?] It is possible to install `py-js` directly into `$HOME/Documents/Max 8/Packages`, but it requires moving the place of compilation to a location in your filesystem that is not exposed to errors due to icloud syncing or spaces in the path. This split is possible, but it is not recommended for the purposes of this quickstart.
114114

115-
4. Install [cython](https://cython.org) via `pip3 install cython`, required for translating the cython-based `api.pyx`, which wraps the the Max c-api, to c.
115+
4. Optionally, install [cython](https://cython.org) via `pip3 install cython`, if you want to make changes to the cython-based `api.pyx` module, which wraps the Max c-api.
116116

117117
5. To build only the `py` and `pyjs` externals, type the following in the root directory of the `py-js` project (other installation options are detailed below):
118118

@@ -260,4 +260,4 @@ Thanks to Greg Neagle for zeroing in on the relocatability problem and sharing h
260260
[zedit]: https://github.com/shakfu/py-js/tree/main/source/projects/zedit
261261
[mpy]: https://github.com/shakfu/py-js/tree/main/source/projects/mpy
262262
[jmx]: https://github.com/shakfu/py-js/tree/main/source/projects/jmx
263-
[zthread]: https://github.com/shakfu/py-js/tree/main/source/projects/zthread
263+
[ztp]: https://github.com/shakfu/py-js/tree/main/source/projects/ztp

‎source/projects/README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,13 @@ For static compilation, the dependencies are `libzmq.a` (itself depending on `li
6161

6262
### zpy
6363

64-
The `zpy` consists of relatively thin zeromq (using the czmq wrapper) client embedded in a Max external. It talks to a corresponding server (written in python3) which is run (currently manually) in a separate process in a REQUEST-REPLY pattern.
64+
The `zpy` consists of relatively thin zeromq (using the czmq wrapper) client embedded in a Max external. It talks to a corresponding server (written in python3) which is run (currently manually) in a separate process in a REQUEST-REPLY pattern.
6565

66-
This prototype blocks the ui thread when it is run. The next example, `zthread`, solves this issue.
66+
This prototype blocks the ui thread when it is run. The next example, `ztp`, solves this issue.
6767

68-
### zthread
68+
### ztp
6969

70-
`zthread` is a `zeromq` client + Max threads to make it non-blocking. This works: one thread per zmq socket as per the zmq rules.
70+
The `ztp` external, the name refers to python, threaded and zeromq, is a `zeromq` client with Max threads to make it non-blocking and it spawns a zeromq python interpreter server. This works: one thread per zmq socket as per the zmq rules.
7171

7272
### jmx
7373

‎source/projects/zthread/CHANGELOG.md

-6
This file was deleted.

‎source/projects/zthread/README.md

-9
This file was deleted.

‎source/projects/ztp/CHANGELOG.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# CHANGELOG for `ztp` object
2+
3+
[0.1.0]
4+
5+
- Renamed this project from `zthread` to `ztp`
6+
7+
- Successful proof-of-concept project created to demonstrate accessing a spawned python interpreter via the use of threads and zeromq channels in order to prevent blocking.
8+

‎source/projects/zthread/CMakeLists.txt ‎source/projects/ztp/CMakeLists.txt

File renamed without changes.

‎source/projects/ztp/README.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# ztp: the zeromq + threads + python Max external
2+
3+
```text
4+
┌─────────────────────────────────────────────────┐
5+
│┌───────────┐ ┌───────────┐│
6+
││ │ │python code││
7+
││ client │◀────────zeromq───────▶│ server ││
8+
││ │ │ (spawned) ││
9+
│└───────────┘ └───────────┘│
10+
│ ztp external │
11+
└─────────────────────────────────────────────────┘
12+
```
13+
14+
The `ztp` external (the name refers to python, threads and zeromq) uses `zmq` with threading for non-blocking communication with a spawned python code interpretation server which evaluates and executes python code and sends back the result.
15+
16+
The combination of threads, zeromq and remote process mgmt of the spawned server make this much more usable than `zpy`, an earlier effort which lacked threads and which suffered from blocking during communication with the server.
17+
18+
## Requires
19+
20+
```bash
21+
brew install zmq
22+
```
23+
24+
## Learnings
25+
26+
- This works: one thread per zmq socket as per the zmq rules.
27+
28+
-

‎source/projects/zthread/server.py ‎source/projects/ztp/server.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ def py_eval(code: str) -> Optional[Any]:
9696

9797

9898
def serve():
99-
log = logging.getLogger("zthread")
99+
log = logging.getLogger("ztp")
100100
log.info("server starting...")
101101

102102
with zmq.Context() as ctx:
@@ -111,7 +111,7 @@ def serve():
111111

112112
msg = message.decode()
113113

114-
if msg == 'ZTHREAD_EXIT':
114+
if msg == 'ZTP_EXIT':
115115
time.sleep(0.2)
116116
socket.send_string("closing connection")
117117
time.sleep(0.2)

‎source/projects/zthread/tests/process/hello.py ‎source/projects/ztp/tests/process/hello.py

File renamed without changes.

‎source/projects/zthread/tests/process/hello.sh ‎source/projects/ztp/tests/process/hello.sh

File renamed without changes.

‎source/projects/zthread/tests/process/run_cmds.c ‎source/projects/ztp/tests/process/run_cmds.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// alternative run_cmd functions for zthread.c
1+
// alternative run_cmd functions for ztp.c
22

33
#define PYTHON_EXE "/absolute-path-to/python3"
44

‎source/projects/zthread/tests/process/test_spawn.c ‎source/projects/ztp/tests/process/test_spawn.c

File renamed without changes.

‎source/projects/zthread/tests/process/test_spawn2.c ‎source/projects/ztp/tests/process/test_spawn2.c

File renamed without changes.

‎source/projects/zthread/tests/safeeval.py ‎source/projects/ztp/tests/safeeval.py

File renamed without changes.

‎source/projects/zthread/tests/threading/README.md ‎source/projects/ztp/tests/threading/README.md

File renamed without changes.

‎source/projects/zthread/tests/threading/build.sh ‎source/projects/ztp/tests/threading/build.sh

File renamed without changes.

‎source/projects/zthread/tests/threading/test_thread1.c ‎source/projects/ztp/tests/threading/test_thread1.c

File renamed without changes.

‎source/projects/zthread/tests/threading/test_thread2.c ‎source/projects/ztp/tests/threading/test_thread2.c

File renamed without changes.

‎source/projects/zthread/tests/threading/test_thread3.c ‎source/projects/ztp/tests/threading/test_thread3.c

File renamed without changes.

‎source/projects/zthread/tests/threading/test_thread4.c ‎source/projects/ztp/tests/threading/test_thread4.c

File renamed without changes.

0 commit comments

Comments
 (0)