2 *------------------------------------------------------------------
3 * svm_queue.h - shared-memory queues
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:
10 * http://www.apache.org/licenses/LICENSE-2.0
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 *------------------------------------------------------------------
20 #ifndef included_svm_queue_h
21 #define included_svm_queue_h
25 typedef struct _svm_queue
27 pthread_mutex_t mutex; /* 8 bytes */
28 pthread_cond_t condvar; /* 8 bytes */
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
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;
52 * Allocate and initialize svm queue
54 * @param nels number of elements on the queue
55 * @param elsize element size, presumably 4 and cacheline-size will
57 * @param pid consumer pid
58 * @return a newly initialized svm queue
60 * The idea is to call this function in the queue consumer,
61 * and e-mail the queue pointer to the producer(s).
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.
67 * You probably want to be on an svm data heap before calling this
70 svm_queue_t *svm_queue_alloc_and_init (int nels, int elsize,
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,
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);
86 * Wait for queue event
88 * Must be called with mutex held.
90 void svm_queue_wait (svm_queue_t * q);
93 * Timed wait for queue event
95 * Must be called with mutex held.
98 * @param timeout time in seconds
99 * @return 0 on success, ETIMEDOUT on timeout or an error
101 int svm_queue_timedwait (svm_queue_t * q, double timeout);
104 * Add element to queue with mutex held
106 * @param elem pointer element data to add
108 void svm_queue_add_raw (svm_queue_t * q, u8 * elem);
111 * Set producer's event fd
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.
116 void svm_queue_set_producer_event_fd (svm_queue_t * q, int fd);
119 * Set consumer's event fd
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.
127 void svm_queue_set_consumer_event_fd (svm_queue_t * q, int fd);
130 * DEPRECATED please use svm_queue_t instead
132 typedef svm_queue_t unix_shared_memory_queue_t;
134 #endif /* included_svm_queue_h */
137 * fd.io coding-style-patch-verification: ON
140 * eval: (c-set-style "gnu")