src/svm/queue.h

   1 /*
   2  *------------------------------------------------------------------
   3  * svm_queue.h - shared-memory queues
   4  *
   5  * Copyright (c) 2009 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 - must be used only in combination
  43                              with condvars */
  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                              must be used only in combination with condvars */
  48 } svm_q_conditional_wait_t;
  49
  50 /**
  51  * Allocate and initialize svm queue
  52  *
  53  * @param nels          number of elements on the queue
  54  * @param elsize        element size, presumably 4 and cacheline-size will
  55  *                      be popular choices.
  56  * @param pid           consumer pid
  57  * @return              a newly initialized svm queue
  58  *
  59  * The idea is to call this function in the queue consumer,
  60  * and e-mail the queue pointer to the producer(s).
  61  *
  62  * The vpp process / main thread allocates one of these
  63  * at startup; its main input queue. The vpp main input queue
  64  * has a pointer to it in the shared memory segment header.
  65  *
  66  * You probably want to be on an svm data heap before calling this
  67  * function.
  68  */
  69 svm_queue_t *svm_queue_alloc_and_init (int nels, int elsize,
  70                                        int consumer_pid);
  71 svm_queue_t *svm_queue_init (void *base, int nels, int elsize);
  72 void svm_queue_free (svm_queue_t * q);
  73 int svm_queue_add (svm_queue_t * q, u8 * elem, int nowait);
  74 int svm_queue_add2 (svm_queue_t * q, u8 * elem, u8 * elem2, int nowait);
  75 int svm_queue_sub (svm_queue_t * q, u8 * elem, svm_q_conditional_wait_t cond,
  76                    u32 time);
  77 int svm_queue_sub2 (svm_queue_t * q, u8 * elem);
  78 void svm_queue_lock (svm_queue_t * q);
  79 void svm_queue_unlock (svm_queue_t * q);
  80 int svm_queue_is_full (svm_queue_t * q);
  81 int svm_queue_add_nolock (svm_queue_t * q, u8 * elem);
  82 int svm_queue_sub_raw (svm_queue_t * q, u8 * elem);
  83
  84 /**
  85  * Wait for queue event
  86  *
  87  * Must be called with mutex held.
  88  */
  89 void svm_queue_wait (svm_queue_t * q);
  90
  91 /**
  92  * Timed wait for queue event
  93  *
  94  * Must be called with mutex held.
  95  *
  96  * @param q             svm queue
  97  * @param timeout       time in seconds
  98  * @return              0 on success, ETIMEDOUT on timeout or an error
  99  */
 100 int svm_queue_timedwait (svm_queue_t * q, double timeout);
 101
 102 /**
 103  * Add element to queue with mutex held
 104  * @param q             queue
 105  * @param elem          pointer element data to add
 106  */
 107 void svm_queue_add_raw (svm_queue_t * q, u8 * elem);
 108
 109 /**
 110  * Set producer's event fd
 111  *
 112  * When the producer must generate an event it writes 1 to the provided fd.
 113  * Once this is set, condvars are not used anymore for signaling.
 114  */
 115 void svm_queue_set_producer_event_fd (svm_queue_t * q, int fd);
 116
 117 /**
 118  * Set consumer's event fd
 119  *
 120  * When the consumer must generate an event it writes 1 to the provided fd.
 121  * Although in practice the two fds point to the same underlying file
 122  * description, because the producer and consumer are different processes
 123  * the descriptors will be different. It's the caller's responsibility to
 124  * ensure the file descriptors are properly exchanged between the two peers.
 125  */
 126 void svm_queue_set_consumer_event_fd (svm_queue_t * q, int fd);
 127
 128 /*
 129  * DEPRECATED please use svm_queue_t instead
 130  */
 131 typedef svm_queue_t unix_shared_memory_queue_t;
 132
 133 #endif /* included_svm_queue_h */
 134
 135 /*
 136  * fd.io coding-style-patch-verification: ON
 137  *
 138  * Local Variables:
 139  * eval: (c-set-style "gnu")
 140  * End:
 141  */