X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=src%2Fsvm%2Fqueue.h;h=2630f17a86ced045d75f7650d8f2f0025e5b04e2;hb=c5df8c71c;hp=68a63d769b626c4c5e9fcb9eb69db4d3246e203a;hpb=3c2fed5145d9e40a9ecd178c2866c813eddc6203;p=vpp.git

diff --git a/src/svm/queue.h b/src/svm/queue.h
index 68a63d769b6..2630f17a86c 100644
--- a/src/svm/queue.h
+++ b/src/svm/queue.h
@@ -2,7 +2,7 @@
  *------------------------------------------------------------------
  * svm_queue.h - shared-memory queues
  *
- * Copyright (c) 2009 Cisco and/or its affiliates.
+ * Copyright (c) 2009-2019 Cisco and/or its affiliates.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at:
@@ -32,32 +32,44 @@ typedef struct _svm_queue
   int maxsize;
   int elsize;
   int consumer_pid;
-  int signal_when_queue_non_empty;
+  int producer_evtfd;
+  int consumer_evtfd;
   char data[0];
 } svm_queue_t;
 
 typedef enum
 {
-  /**
-   * blocking call
-   */
-  SVM_Q_WAIT = 0,
-
-  /**
-   * non-blocking call
-   */
-  SVM_Q_NOWAIT,
-
-  /**
-   * blocking call, return on signal or time-out
-   */
-  SVM_Q_TIMEDWAIT,
+  SVM_Q_WAIT = 0,	/**< blocking call - best used in combination with
+			     condvars, for eventfds we don't yield the cpu */
+  SVM_Q_NOWAIT,		/**< non-blocking call - works with both condvar and
+			     eventfd signaling */
+  SVM_Q_TIMEDWAIT,	/**< blocking call, returns on signal or time-out -
+			     best used in combination with condvars, with
+			     eventfds we don't yield the cpu */
 } svm_q_conditional_wait_t;
 
-svm_queue_t *svm_queue_init (int nels,
-			     int elsize,
-			     int consumer_pid,
-			     int signal_when_queue_non_empty);
+/**
+ * Allocate and initialize svm queue
+ *
+ * @param nels		number of elements on the queue
+ * @param elsize	element size, presumably 4 and cacheline-size will
+ *          		be popular choices.
+ * @param pid   	consumer pid
+ * @return 		a newly initialized svm queue
+ *
+ * The idea is to call this function in the queue consumer,
+ * and e-mail the queue pointer to the producer(s).
+ *
+ * The vpp process / main thread allocates one of these
+ * at startup; its main input queue. The vpp main input queue
+ * has a pointer to it in the shared memory segment header.
+ *
+ * You probably want to be on an svm data heap before calling this
+ * function.
+ */
+svm_queue_t *svm_queue_alloc_and_init (int nels, int elsize,
+				       int consumer_pid);
+svm_queue_t *svm_queue_init (void *base, int nels, int elsize);
 void svm_queue_free (svm_queue_t * q);
 int svm_queue_add (svm_queue_t * q, u8 * elem, int nowait);
 int svm_queue_add2 (svm_queue_t * q, u8 * elem, u8 * elem2, int nowait);
@@ -70,6 +82,24 @@ int svm_queue_is_full (svm_queue_t * q);
 int svm_queue_add_nolock (svm_queue_t * q, u8 * elem);
 int svm_queue_sub_raw (svm_queue_t * q, u8 * elem);
 
+/**
+ * Wait for queue event
+ *
+ * Must be called with mutex held.
+ */
+void svm_queue_wait (svm_queue_t * q);
+
+/**
+ * Timed wait for queue event
+ *
+ * Must be called with mutex held.
+ *
+ * @param q		svm queue
+ * @param timeout	time in seconds
+ * @return 		0 on success, ETIMEDOUT on timeout or an error
+ */
+int svm_queue_timedwait (svm_queue_t * q, double timeout);
+
 /**
  * Add element to queue with mutex held
  * @param q		queue
@@ -77,6 +107,25 @@ int svm_queue_sub_raw (svm_queue_t * q, u8 * elem);
  */
 void svm_queue_add_raw (svm_queue_t * q, u8 * elem);
 
+/**
+ * Set producer's event fd
+ *
+ * When the producer must generate an event it writes 1 to the provided fd.
+ * Once this is set, condvars are not used anymore for signaling.
+ */
+void svm_queue_set_producer_event_fd (svm_queue_t * q, int fd);
+
+/**
+ * Set consumer's event fd
+ *
+ * When the consumer must generate an event it writes 1 to the provided fd.
+ * Although in practice the two fds point to the same underlying file
+ * description, because the producer and consumer are different processes
+ * the descriptors will be different. It's the caller's responsibility to
+ * ensure the file descriptors are properly exchanged between the two peers.
+ */
+void svm_queue_set_consumer_event_fd (svm_queue_t * q, int fd);
+
 /*
  * DEPRECATED please use svm_queue_t instead
  */