refactor: minor example simplification

Signed-off-by: Christopher Arndt <chris@chrisarndt.de>

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Christopher Arndt <info@chrisarndt.de>
+Copyright (c) 2022 - 2023 Christopher Arndt <info@chrisarndt.de>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -7,10 +7,12 @@ A [Nim] wrapper for the [JACK] [C API]
 
 This software is in *alpha status* and has no official release yet.
 
-The basic JACK APIs (client lifecycle, ports, callbacks, MIDI, transport) have
-been wrapped and are functional (see [examples]), but latency, threading and
-meta-data APIs still need wrapping. Also, symbol names may still be changed
-and things moved around before the first public release.
+The majority of JACK client APIs have been wrapped and are functional (see
+[examples]), but some APIs (e.g. threading and ringbuffers) still need
+wrapping. Others, like the server control or the deprecated session API, will
+probably not covered by these bindings. While this project is in alpha or beta
+stage, symbol names may still be changed and things moved around before the
+first public release.
 
 Also, I plan to add a higher-level abstraction on top of the direct mapping
 from Nim procs and types to C functions and types, probably in the form of
@@ -24,7 +26,8 @@ JACK application.
 * Clone this repository.
 * Change into the `jacket` directory.
 * Run [`nimble install`] (or `nimble develop`).
-* Run the examples with `nim compile --run examples/<example>.nim`.
+* Run the examples with `nim compile --run examples/<example>.nim` (some also
+  need `--threads:on`).
 
 
 ## License

examples/jacket_list_all_properties.nim

@@ -2,7 +2,6 @@ import std/[logging, strformat]
 import jacket
 
 var
-    jclient: ClientP
     status: cint
     descs: ptr UncheckedArray[Description]
 
@@ -15,7 +14,7 @@ proc errorCb(msg: cstring) {.cdecl.} =
 
 addHandler(log)
 setErrorFunction(errorCb)
-jclient = clientOpen("jacket_property", NullOption.ord, status.addr)
+let jclient = clientOpen("jacket_property", NullOption.ord, status.addr)
 debug "JACK server status: " & $status
 
 if jclient == nil:
@@ -25,10 +24,8 @@ if jclient == nil:
 let numDescs = getAllProperties(descs)
 
 if numDescs != -1:
-    var desc: Description
-
     for i in 0..<numDescs:
-        desc = descs[i]
+        var desc = descs[i]
         echo fmt"Subject: {desc.subject}"
 
         if desc.property_cnt > 0:

src/jacket.nim

@@ -30,6 +30,7 @@ const
 type
     Time* = uint64
     NFrames* = uint32
+    IntClient = uint64
     Uuid* = uint64
     PortId* = uint32
     PortTypeId* = uint32
@@ -85,6 +86,10 @@ type
         PortIsTerminal = 0x10
 
 type
+    LatencyRange* = object
+        min*: NFrames
+        max*: NFrames
+
     LatencyCallbackMode* {.size: sizeof(cint) pure.} = enum
         CaptureLatency,
         PlaybackLatency
@@ -239,10 +244,6 @@ proc free*(`ptr`: pointer) {.importc: "jack_free".}
 proc clientOpen*(clientName: cstring; options: cint; status: ptr cint): ClientP {.
     varargs, importc: "jack_client_open".}
 
-#[ DEPRECATED
-jack_client_t * jack_client_new (const char *client_name)
-]#
-
 # int jack_client_close (jack_client_t *client)
 proc clientClose*(client: ClientP): cint {.importc: "jack_client_close"}
 
@@ -260,13 +261,6 @@ proc getUuidForClientName*(client: ClientP; clientName: cstring): cstring {.
 proc getClientNameByUuid*(client: ClientP; clientUuid: cstring): cstring {.
     importc: "jack_get_client_name_by_uuid".}
 
-#[ FIXME: not implemented yet
-proc internalClientNew*(clientName: cstring; loadName: cstring; loadInit: cstring): cint {.
-    importc: "jack_internal_client_new".}
-
-proc internalClientClose*(clientName: cstring) {.importc: "jack_internal_client_close".}
-]#
-
 # int jack_activate (jack_client_t *client)
 proc activate*(client: ClientP): cint {.importc: "jack_activate".}
 
@@ -283,16 +277,43 @@ proc getClientPid*(name: cstring): cint {.importc: "jack_get_client_pid".}
 # int jack_is_realtime (jack_client_t *client)
 proc isRealtime*(client: ClientP): cint {.importc: "jack_is_realtime".}
 
-#[ DEPRECATED
-jack_nframes_t jack_thread_wait (jack_client_t *client, int status)
-]#
-
 # jack_nframes_t jack_cycle_wait (jack_client_t* client)
 proc cycleWait*(client: ClientP): NFrames {.importc: "jack_cycle_wait".}
 
 # void jack_cycle_signal (jack_client_t* client, int status)
 proc cycleSignal*(client: ClientP; status: cint) {.importc: "jack_cycle_signal".}
 
+#[ DEPRECATED
+jack_client_t *jack_client_new (const char *client_name)
+jack_nframes_t jack_thread_wait (jack_client_t *client, int status)
+]#
+
+# --------------------------- Internal Clients ----------------------------
+
+# char *jack_get_internal_client_name (jack_client_t *client, jack_intclient_t intclient);
+proc getInternalClientName(client: ClientP; intclient: IntClient): cstring {.
+    importc: "jack_get_internal_client_name".}
+
+# jack_intclient_t jack_internal_client_handle (jack_client_t *client, const char *client_name,
+#                                               jack_status_t *status)
+proc internalClientHandle(client: ClientP; clientName: cstring; status: ptr cint): IntClient {.
+    importc: "jack_internal_client_handle".}
+
+# jack_intclient_t jack_internal_client_load (jack_client_t *client, const char *client_name,
+#                                             jack_options_t options, jack_status_t *status, ...)
+proc internalClientLoad(client: ClientP; clientName: cstring; options: cint; status: ptr cint): IntClient {.
+    varargs, importc: "jack_internal_client_load".}
+
+# jack_status_t jack_internal_client_unload (jack_client_t *client, jack_intclient_t intclient)
+
+proc internalClientUnload(client: ClientP; intclient: IntClient): cint {.
+    importc: "jack_internal_client_unload".}
+
+#[ DEPRECATED
+int jack_internal_client_new (const char * client_name, const char *load_name, const char *load_init)
+void jack_internal_client_close (const char *client_name)
+]#
+
 
 # ------------------------------- Callbacks -------------------------------
 
@@ -358,13 +379,13 @@ proc getSampleRate*(client: ClientP): NFrames {.importc: "jack_get_sample_rate".
 # jack_nframes_t jack_get_buffer_size (jack_client_t *)
 proc getBufferSize*(client: ClientP): NFrames {.importc: "jack_get_buffer_size".}
 
+# float jack_cpu_load (jack_client_t *client)
+proc cpuLoad*(client: ClientP): cfloat {.importc: "jack_cpu_load".}
+
 #[ DEPRECATED
 int jack_engine_takeover_timebase (jack_client_t *)
 ]#
 
-# float jack_cpu_load (jack_client_t *client)
-proc cpuLoad*(client: ClientP): cfloat {.importc: "jack_cpu_load".}
-
 
 # --------------------------------- Ports ---------------------------------
 
@@ -423,14 +444,6 @@ proc portGetConnections*(port: PortP): cstringArray {.importc: "jack_port_get_co
 proc portGetAllConnections*(client: ClientP; port: PortP): cstringArray {.
     importc: "jack_port_get_all_connections".}
 
-#[ DEPRECATED
-int jack_port_tie (jack_port_t *src, jack_port_t *dst)
-
-int jack_port_untie (jack_port_t *port)
-
-int jack_port_set_name (jack_port_t *port, const char *port_name)
-]#
-
 # int jack_port_rename (jack_client_t* client, jack_port_t *port, const char *port_name)
 proc portRename*(client: ClientP; port: PortP; portName: cstring): cint {.importc: "jack_port_rename".}
 
@@ -458,6 +471,12 @@ proc portEnsureMonitor*(port: PortP; onoff: cint): cint {.
 # int jack_port_monitoring_input (jack_port_t *port)
 proc portMonitoringInput*(port: PortP): cint {.importc: "jack_port_monitoring_input".}
 
+#[ DEPRECATED
+int jack_port_tie (jack_port_t *src, jack_port_t *dst)
+int jack_port_untie (jack_port_t *port)
+int jack_port_set_name (jack_port_t *port, const char *port_name)
+]#
+
 
 # ------------------------------ Port Lookup ------------------------------
 
@@ -532,24 +551,22 @@ proc midiGetLostEventCount*(portBuffer: pointer): uint32 {.importc: "jack_midi_g
 
 # -------------------------------- Latency --------------------------------
 
-#[ FIXME: not implemented yet
-# void jack_port_set_latency (jack_port_t *port, jack_nframes_t)
-proc portSetLatency*(port: PortP; a2: NFrames) {.importc: "jack_port_set_latency".}
-
 # void jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range)
-proc portGetLatencyRange*(port: PortP; mode: LatencyCallbackMode;
-                         range: ptr LatencyRange) {.importc: "jack_port_get_latency_range".}
+proc portGetLatencyRange*(port: PortP; mode: LatencyCallbackMode; range: ptr LatencyRange) {.
+    importc: "jack_port_get_latency_range".}
 
-proc portSetLatencyRange*(port: PortP; mode: LatencyCallbackMode;
-                         range: ptr LatencyRange) {.importc: "jack_port_set_latency_range".}
+# void jack_port_set_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range)
+proc portSetLatencyRange*(port: PortP; mode: LatencyCallbackMode; range: ptr LatencyRange) {.
+    importc: "jack_port_set_latency_range".}
 
+# int jack_recompute_total_latencies (jack_client_t *)
 proc recomputeTotalLatencies*(client: ClientP): cint {.importc: "jack_recompute_total_latencies".}
 
-proc portGetLatency*(port: PortP): NFrames {.importc: "jack_port_get_latency".}
-
-proc portGetTotalLatency*(client: ClientP; port: PortP): NFrames {.importc: "jack_port_get_total_latency".}
-
-proc recomputeTotalLatency*(a1: ClientP; port: PortP): cint {.importc: "jack_recompute_total_latency".}
+#[ DEPRECATED
+jack_nframes_t jack_port_get_latency (jack_port_t *port)
+jack_nframes_t jack_port_get_total_latency (jack_client_t *, jack_port_t *port)
+void jack_port_set_latency (jack_port_t *port, jack_nframes_t)
+int jack_recompute_total_latency (jack_client_t *, jack_port_t *port)
 ]#