Add comments to the perlglue.

1 files changed, 31 insertions, 2 deletions

diff --git a/libvxi11client/perlbits/perlglue.c b/libvxi11client/perlbits/perlglue.c
index 096f7a7..dafc707 100644
--- a/libvxi11client/perlbits/perlglue.c
+++ b/libvxi11client/perlbits/perlglue.c
@@ -9,6 +9,7 @@
 #include <stdio.h>
 #endif
 
+// thread safe queue for stacking up interrupts
 static GAsyncQueue* interruptqueue;
 
 typedef struct {
@@ -29,12 +30,24 @@ static void freelast() {
 	}
 }
 
+/**
+ * This is the callback that is passed to the interrupt
+ * thread for it to run each time it gets an interrupt.
+ * It creates a new event, puts the handle in place and
+ * puts in the in the queue for someone to collect later
+ */
+
 static void interruptcallback(gchar* handle) {
 	Event* event = g_malloc(sizeof(Event));
 	event->handle = handle;
 	g_async_queue_push(interruptqueue, event);
 }
 
+/**
+ * This is just for perl, it creates a new "context" and passes
+ * that to the real open function
+ */
+
 VXI11Context* glue_open(char* address, char* device) {
 	VXI11Context* context = malloc(sizeof(VXI11Context));
 	if (context == NULL )
@@ -45,12 +58,20 @@ VXI11Context* glue_open(char* address, char* device) {
 	return context;
 }
 
+/**
+ * Create a queue, start the interrupt server, and give it our callback
+ */
+
 int glue_start_interrupt_server() {
 	interruptqueue = g_async_queue_new();
 	g_async_queue_ref(interruptqueue);
 	return vxi11_start_interrupt_server(interruptcallback);
 }
 
+/**
+ * Close down the interrupt server and free everything
+ */
+
 int glue_stop_interrupt_server() {
 	int ret = vxi11_stop_interrupt_server();
 	Event* event = NULL;
@@ -64,6 +85,13 @@ int glue_stop_interrupt_server() {
 	return ret;
 }
 
+/**
+ * Block until an interrupt happens. A time out of -1 while block until an
+ * interrupt happens or forever(!), 0 will not block and only return a handle
+ * if an interrupt already happened, any value > 0 will return instantly if there
+ * is a queued interrupt or wait for one to happen up to the timeout.
+ */
+
 char* glue_wait_for_interrupt(int timeout) {
 	if (interruptqueue == NULL ) {
 #ifdef DEBUG
@@ -72,8 +100,9 @@ char* glue_wait_for_interrupt(int timeout) {
 		return NULL ;
 	}
 
-	// if we have a timeout pop with a time out
-	// otherwise block until an interrupt happens
+	// if timeout > 0 pop with a time out,
+	// if the timeout is 0 try to pop but don't block
+	// if the timeout is -1 block until an interrupt happens
 	freelast();
 
 	if (timeout > 0) {