src/svm/queue.h

   1 /*
   2  *------------------------------------------------------------------
   3  * svm_queue.h - shared-memory queues
   4  *
   5  * Copyright (c) 2009-2019 Cisco and/or its affiliates.
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at:
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *------------------------------------------------------------------
  18  */
  19
  20 #ifndef included_svm_queue_h
  21 #define included_svm_queue_h
  22
  23 #include <pthread.h>
  24
  25 typedef struct _svm_queue
  26 {
  27   pthread_mutex_t mutex;        /* 8 bytes */
  28   pthread_cond_t condvar;       /* 8 bytes */
  29   int head;
  30   int tail;
  31   volatile int cursize;
  32   int maxsize;
  33   int elsize;
  34   int consumer_pid;
  35   int producer_evtfd;
  36   int consumer_evtfd;
  37   char data[0];
  38 } svm_queue_t;
  39
  40 typedef enum
  41 {
  42   SVM_Q_WAIT = 0,       /**< blocking call - best used in combination with
  43                              condvars, for eventfds we don't yield the cpu */
  44   SVM_Q_NOWAIT,         /**< non-blocking call - works with both condvar and
  45                              eventfd signaling */
  46   SVM_Q_TIMEDWAIT,      /**< blocking call, returns on signal or time-out -
  47                              best used in combination with condvars, with
  48                              eventfds we don't yield the cpu */
  49 } svm_q_conditional_wait_t;
  50
  51 /**
  52  * Allocate and initialize svm queue
  53  *
  54  * @param nels          number of elements on the queue
  55  * @param elsize        element size, presumably 4 and cacheline-size will
  56  *                      be popular choices.
  57  * @param pid           consumer pid
  58  * @return              a newly initialized svm queue
  59  *
  60  * The idea is to call this function in the queue consumer,
  61  * and e-mail the queue pointer to the producer(s).
  62  *
  63  * The vpp process / main thread allocates one of these
  64  * at startup; its main input queue. The vpp main input queue
  65  * has a pointer to it in the shared memory segment header.
  66  *
  67  * You probably want to be on an svm data heap before calling this
  68  * function.
  69  */
  70 svm_queue_t *svm_queue_alloc_and_init (int nels, int elsize,
  71                                        int consumer_pid);
  72 svm_queue_t *svm_queue_init (void *base, int nels, int elsize);
  73 void svm_queue_free (svm_queue_t * q);
  74 int svm_queue_add (svm_queue_t * q, u8 * elem, int nowait);
  75 int svm_queue_add2 (svm_queue_t * q, u8 * elem, u8 * elem2, int nowait);
  76 int svm_queue_sub (svm_queue_t * q, u8 * elem, svm_q_conditional_wait_t cond,
  77                    u32 time);
  78 int svm_queue_sub2 (svm_queue_t * q, u8 * elem);
  79 void svm_queue_lock (svm_queue_t * q);
  80 void svm_queue_send_signal (svm_queue_t * q, u8 is_prod);
  81 void svm_queue_unlock (svm_queue_t * q);
  82 int svm_queue_is_full (svm_queue_t * q);
  83 int svm_queue_add_nolock (svm_queue_t * q, u8 * elem);
  84 int svm_queue_sub_raw (svm_queue_t * q, u8 * elem);
  85
  86 /**
  87  * Wait for queue event
  88  *
  89  * Must be called with mutex held.
  90  */
  91 void svm_queue_wait (svm_queue_t * q);
  92
  93 /**
  94  * Timed wait for queue event
  95  *
  96  * Must be called with mutex held.
  97  *
  98  * @param q             svm queue
  99  * @param timeout       time in seconds
 100  * @return              0 on success, ETIMEDOUT on timeout or an error
 101  */
 102 int svm_queue_timedwait (svm_queue_t * q, double timeout);
 103
 104 /**
 105  * Add element to queue with mutex held
 106  * @param q             queue
 107  * @param elem          pointer element data to add
 108  */
 109 void svm_queue_add_raw (svm_queue_t * q, u8 * elem);
 110
 111 /**
 112  * Set producer's event fd
 113  *
 114  * When the producer must generate an event it writes 1 to the provided fd.
 115  * Once this is set, condvars are not used anymore for signaling.
 116  */
 117 void svm_queue_set_producer_event_fd (svm_queue_t * q, int fd);
 118
 119 /**
 120  * Set consumer's event fd
 121  *
 122  * When the consumer must generate an event it writes 1 to the provided fd.
 123  * Although in practice the two fds point to the same underlying file
 124  * description, because the producer and consumer are different processes
 125  * the descriptors will be different. It's the caller's responsibility to
 126  * ensure the file descriptors are properly exchanged between the two peers.
 127  */
 128 void svm_queue_set_consumer_event_fd (svm_queue_t * q, int fd);
 129
 130 /*
 131  * DEPRECATED please use svm_queue_t instead
 132  */
 133 typedef svm_queue_t unix_shared_memory_queue_t;
 134
 135 #endif /* included_svm_queue_h */
 136
 137 /*
 138  * fd.io coding-style-patch-verification: ON
 139  *
 140  * Local Variables:
 141  * eval: (c-set-style "gnu")
 142  * End:
 143  */