Return a pkl_exec_t instance when initialising the C library

This allows consumers to control how many instances they wish to have,
and can also control the thread-local behaviour themselves.

Author: KushalP

libpkl/src/main/c/pkl.c

@@ -24,97 +24,107 @@
 
 #include <pkl.h>
 
-#ifndef NULL
-  #define NULL 0
-#endif
+void pkl_runtime_cleanup(pkl_exec_t *pexec) {
+  pkl_internal_server_stop(pexec->graal_isolatethread);
+  pkl_internal_close(pexec->graal_isolatethread);
+  pexec->graal_isolatethread = NULL;
+}
 
-pthread_mutex_t graal_mutex;
-graal_isolatethread_t *graal_isolatethread = NULL;
+pkl_exec_t *pkl_init(PklMessageResponseHandler handler, void *userData) {
+  pkl_exec_t *pexec = calloc(1, sizeof(pkl_exec_t));
 
-int pkl_attach_thread() {
-  graal_isolate_t *graal_isolate = graal_get_isolate(graal_isolatethread);
-  if (graal_isolate == NULL) {
-    perror("pkl_attach_thread: couldn't get isolate");
-    return -1;
+  if (pexec == NULL) {
+    perror("pkl_init: couldn't allocate pkl_exec_t");
+    return NULL;
   }
 
-  if (graal_attach_thread(graal_isolate, &graal_isolatethread) != 0) {
-    perror("pkl_attach_thread: couldn't attach thread");
-    return -1;
+  if (pthread_mutex_init(&pexec->graal_mutex, NULL) != 0) {
+    perror("pkl_init: couldn't initialise pthread_mutex");
+    pkl_runtime_cleanup(pexec);
+    free(pexec);
+    return NULL;
   }
 
-  return 0;
-}
+  if (pthread_mutex_lock(&pexec->graal_mutex) != 0) {
+    perror("pkl_init: couldn't lock mutex");
+    pkl_runtime_cleanup(pexec);
+    pthread_mutex_destroy(&pexec->graal_mutex);
+    free(pexec);
+    return NULL;
+  }
 
-int pkl_init(PklMessageResponseHandler handler, void *userData) {
-  if (graal_isolatethread != NULL) {
-    perror("pkl_init: graal_isolatethread is already initialised");
-    return -1;
+  pexec->graal_isolatethread = pkl_internal_init();
+  pkl_internal_register_response_handler(pexec->graal_isolatethread, handler,
+                                         userData);
+  pkl_internal_server_start(pexec->graal_isolatethread);
+
+  if (pthread_mutex_unlock(&pexec->graal_mutex) != 0) {
+    perror("pkl_init: couldn't unlock mutex");
+    return NULL;
   }
 
-  if (pthread_mutex_init(&graal_mutex, NULL) != 0) {
-    perror("pkl_init: couldn't initialise pthread_mutex");
+  return pexec;
+};
+
+int pkl_send_message(pkl_exec_t *pexec, int length, char *message) {
+  if (pexec == NULL) {
+    perror("pkl_send_message: pexec is NULL");
     return -1;
   }
 
-  if (pthread_mutex_lock(&graal_mutex) != 0) {
+  if (message == NULL) {
+    perror("pkl_send_message: message is NULL");
     return -1;
   }
 
-  graal_isolatethread = pkl_internal_init();
-  pkl_internal_register_response_handler(graal_isolatethread, handler, userData);
-  pkl_internal_server_start(graal_isolatethread);
-  pthread_mutex_unlock(&graal_mutex);
-
-  return 0;
-};
-
-int pkl_send_message(int length, char *message) {
-  if (pthread_mutex_lock(&graal_mutex) != 0) {
+  if (pthread_mutex_lock(&pexec->graal_mutex) != 0) {
+    perror("pkl_send_message: couldn't lock mutex");
     return -1;
   }
 
-  if (pkl_attach_thread() != 0) {
-    perror("pkl_send_message: couldn't attach thread");
+  pkl_internal_send_message(pexec->graal_isolatethread, length, message);
+
+  if (pthread_mutex_unlock(&pexec->graal_mutex) != 0) {
+    perror("pkl_send_message: couldn't unlock mutex");
     return -1;
   }
 
-  pkl_internal_send_message(graal_isolatethread, length, message);
-  pthread_mutex_unlock(&graal_mutex);
-
   return 0;
 };
 
-int pkl_close() {
-  if (pthread_mutex_lock(&graal_mutex) != 0) {
+int pkl_close(pkl_exec_t *pexec) {
+  if (pexec == NULL) {
+    perror("pkl_close: pexec is NULL");
     return -1;
   }
 
-  if (pkl_attach_thread() != 0) {
-    perror("pkl_send_message: couldn't attach thread");
+  if (pthread_mutex_lock(&pexec->graal_mutex) != 0) {
+    perror("pkl_close: couldn't lock mutex");
     return -1;
   }
 
-  pkl_internal_server_stop(graal_isolatethread);
-  pkl_internal_close(graal_isolatethread);
-  graal_isolatethread = NULL;
+  pkl_runtime_cleanup(pexec);
 
-  if (pthread_mutex_unlock(&graal_mutex) != 0) {
+  if (pthread_mutex_unlock(&pexec->graal_mutex) != 0) {
+    perror("pkl_close: couldn't unlock mutex");
     return -1;
   }
 
-  if (pthread_mutex_destroy(&graal_mutex) != 0) {
+  if (pthread_mutex_destroy(&pexec->graal_mutex) != 0) {
+    perror("pkl_close: couldn't destroy mutex");
     return -1;
   }
 
+  free(pexec);
+
   return 0;
 };
 
-char* pkl_version() {
-  if (pkl_attach_thread() != 0) {
-    perror("pkl_version: couldn't attach thread");
+char *pkl_version(pkl_exec_t *pexec) {
+  if (pexec == NULL) {
+    perror("pkl_version: pexec is NULL");
     return NULL;
   }
 
-  return pkl_internal_version(graal_isolatethread);
+  return pkl_internal_version(pexec->graal_isolatethread);
 }

libpkl/src/main/c/pkl.h

@@ -15,6 +15,22 @@
  */
 // pkl.h
 
+#include <pthread.h>
+#include <graal_isolate.h>
+
+/**
+ * Pkl executor instance that manages communication with the Pkl runtime.
+ *
+ * Instances should be created via pkl_init() and destroyed via pkl_close().
+ *
+ * All operations on this struct should be considered thread-safe due to
+ * internal synchronization via the graal_mutex.
+ */
+typedef struct PKL_EXEC_T {
+  pthread_mutex_t graal_mutex;
+  graal_isolatethread_t *graal_isolatethread;
+} pkl_exec_t;
+
 /**
  * The callback that gets called when a message is received from Pkl.
  *
@@ -30,30 +46,36 @@ typedef void (*PklMessageResponseHandler)(int length, char *message, void *userD
  * @param handler   The callback that gets called when a message is received from Pkl.
  * @param userData  User-defined data that gets passed to handler.
  *
- * @return -1 on failure, 0 on success.
+ * @return NULL on failure, a pointer to a pkl_exec_t on success.
  */
-int pkl_init(PklMessageResponseHandler handler, void *userData);
+pkl_exec_t *pkl_init(PklMessageResponseHandler handler, void *userData);
 
 /**
  * Send a message to Pkl, providing the length and a pointer to the first byte.
  *
+ * @param pexec     The Pkl executor instance.
  * @param length    The length of the message, in bytes.
  * @param message   The message to send to Pkl.
  *
  * @return -1 on failure, 0 on success.
  */
-int pkl_send_message(int length, char *message);
+int pkl_send_message(pkl_exec_t *pexec, int length, char *message);
 
 /**
- * Cleans up any resources that were created as part of the `pkl_init` process.
+ * Cleans up any resources that were created as part of the `pkl_init` process
+ * for our `pkl_exec_t` instance.
+ *
+ * @param pexec     The Pkl executor instance.
  *
  * @return -1 on failure, 0 on success.
  */
-int pkl_close();
+int pkl_close(pkl_exec_t *pexec);
 
 /**
  * Returns the version of Pkl in use.
  *
+ * @param pexec     The Pkl executor instance.
+ *
  * @return a string with the version information.
  */
-char* pkl_version();
+char *pkl_version(pkl_exec_t *pexec);

libpkl/src/nativeTest/kotlin/org/pkl/libpkl/LibPklJNA.kt

@@ -30,11 +30,11 @@ interface LibPklJNA : Library {
     fun invoke(length: Int, message: Pointer, userData: Pointer?)
   }
 
-  fun pkl_init(handler: PklMessageResponseHandler, userData: Pointer?): Int
+  fun pkl_init(handler: PklMessageResponseHandler, userData: Pointer?): Pointer?
 
-  fun pkl_send_message(length: Int, message: ByteArray): Int
+  fun pkl_send_message(pexec: Pointer, length: Int, message: ByteArray): Int
 
-  fun pkl_close(): Int
+  fun pkl_close(pexec: Pointer): Int
 
-  fun pkl_version(): String
+  fun pkl_version(pexec: Pointer): String
 }

libpkl/src/nativeTest/kotlin/org/pkl/libpkl/LibPklMessageTransport.kt

@@ -32,17 +32,20 @@ class LibPklMessageTransport : MessageTransports.AbstractMessageTransport({}) {
       }
     }
 
+  var pexec: Pointer? = null
+
   override fun doStart() {
-    assertThat(LibPklJNA.INSTANCE.pkl_init(messageResponseHandler, Pointer.NULL)).isEqualTo(0)
+    this.pexec = LibPklJNA.INSTANCE.pkl_init(messageResponseHandler, Pointer.NULL)
+    assertThat(this.pexec).isNotNull()
   }
 
   override fun doClose() {
-    assertThat(LibPklJNA.INSTANCE.pkl_close()).isEqualTo(0)
+    assertThat(LibPklJNA.INSTANCE.pkl_close(pexec!!)).isEqualTo(0)
   }
 
   override fun doSend(message: Message) {
     val bytes = encode(message)
-    LibPklJNA.INSTANCE.pkl_send_message(bytes.size, bytes)
+    LibPklJNA.INSTANCE.pkl_send_message(pexec!!, bytes.size, bytes)
   }
 
   private fun encode(message: Message): ByteArray {

libpkl/src/nativeTest/kotlin/org/pkl/libpkl/LibPklTest.kt

@@ -37,9 +37,11 @@ import org.pkl.core.Release
 class LibPklTest : AbstractServerTest() {
   override lateinit var client: TestTransport
 
+  val delegate = LibPklMessageTransport()
+
   @BeforeEach
   fun beforeEach() {
-    client = TestTransport(LibPklMessageTransport()).also { it.start() }
+    client = TestTransport(delegate).also { it.start() }
   }
 
   @AfterEach
@@ -49,6 +51,10 @@ class LibPklTest : AbstractServerTest() {
 
   @Test
   fun testVersionString() {
-    assertThat(LibPklJNA.INSTANCE.pkl_version()).isEqualTo(Release.current().version.toString())
+    assertThat(delegate.pexec).isNotNull()
+
+    Release.current().version.toString().let { currentVersion ->
+      assertThat(LibPklJNA.INSTANCE.pkl_version(delegate.pexec!!)).isEqualTo(currentVersion)
+    }
   }
 }