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_unlock (svm_queue_t * q);
  81 int svm_queue_is_full (svm_queue_t * q);
  82 int svm_queue_add_nolock (svm_queue_t * q, u8 * elem);
  83 int svm_queue_sub_raw (svm_queue_t * q, u8 * elem);
  84
  85 /**
  86  * Wait for queue event
  87  *
  88  * Must be called with mutex held.
  89  */
  90 void svm_queue_wait (svm_queue_t * q);
  91
  92 /**
  93  * Timed wait for queue event
  94  *
  95  * Must be called with mutex held.
  96  *
  97  * @param q             svm queue
  98  * @param timeout       time in seconds
  99  * @return              0 on success, ETIMEDOUT on timeout or an error
 100  */
 101 int svm_queue_timedwait (svm_queue_t * q, double timeout);
 102
 103 /**
 104  * Add element to queue with mutex held
 105  * @param q             queue
 106  * @param elem          pointer element data to add
 107  */
 108 void svm_queue_add_raw (svm_queue_t * q, u8 * elem);
 109
 110 /**
 111  * Set producer's event fd
 112  *
 113  * When the producer must generate an event it writes 1 to the provided fd.
 114  * Once this is set, condvars are not used anymore for signaling.
 115  */
 116 void svm_queue_set_producer_event_fd (svm_queue_t * q, int fd);
 117
 118 /**
 119  * Set consumer's event fd
 120  *
 121  * When the consumer must generate an event it writes 1 to the provided fd.
 122  * Although in practice the two fds point to the same underlying file
 123  * description, because the producer and consumer are different processes
 124  * the descriptors will be different. It's the caller's responsibility to
 125  * ensure the file descriptors are properly exchanged between the two peers.
 126  */
 127 void svm_queue_set_consumer_event_fd (svm_queue_t * q, int fd);
 128
 129 /*
 130  * DEPRECATED please use svm_queue_t instead
 131  */
 132 typedef svm_queue_t unix_shared_memory_queue_t;
 133
 134 #endif /* included_svm_queue_h */
 135
 136 /*
 137  * fd.io coding-style-patch-verification: ON
 138  *
 139  * Local Variables:
 140  * eval: (c-set-style "gnu")
 141  * End:
 142  */