vlc_interrupt.h 7.51 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*****************************************************************************
 * vlc_interrupt.h:
 *****************************************************************************
 * Copyright (C) 2015 Remlab T:mi
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef VLC_INTERRUPT_H
# define VLC_INTERRUPT_H 1
# include <vlc_threads.h>
24
# ifndef _WIN32
25
#  include <sys/socket.h> /* socklen_t */
26
# else
27 28
#  include <ws2tcpip.h>
# endif
29 30

struct pollfd;
31
struct iovec;
32 33
struct sockaddr;
struct msghdr;
34

35 36
/**
 * @defgroup interrupt Interruptible sleep
37
 * @ingroup thread
38
 * @{
39 40
 * @file
 * This file declares interruptible sleep functions.
41 42 43 44 45
 * @defgroup interrupt_sleep Interruptible sleep functions
 * @{
 */

/**
46 47
 * Interruptible variant of vlc_sem_wait().
 *
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
 * Waits on a semaphore like vlc_sem_wait(). If the calling thread has an
 * interruption context (as set by vlc_interrupt_set()), and another thread
 * invokes vlc_interrupt_raise() on that context, the semaphore is incremented.
 *
 * @warning The calling thread should be the only thread ever to wait on the
 * specified semaphore. Otherwise, interruptions may not be delivered
 * accurately (the wrong thread may be woken up).
 *
 * @note This function is (always) a cancellation point.
 *
 * @return EINTR if the semaphore was incremented due to an interruption,
 * otherwise zero.
 */
VLC_API int vlc_sem_wait_i11e(vlc_sem_t *);

63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
/**
 * Interruptible variant of mwait().
 *
 * Waits for a specified timestamp or, if the calling thread has an
 * interruption context, an interruption.
 *
 * @return EINTR if an interruption occurred, otherwise 0 once the timestamp is
 * reached.
 */
VLC_API int vlc_mwait_i11e(mtime_t);

/**
 * Interruptible variant of msleep().
 *
 * Waits for a specified timeout duration or, if the calling thread has an
 * interruption context, an interruption.
 *
 * @param delay timeout value (in microseconds)
 *
 * @return EINTR if an interruption occurred, otherwise 0 once the timeout
 * expired.
 */
static inline int vlc_msleep_i11e(mtime_t delay)
{
    return vlc_mwait_i11e(mdate() + delay);
}

90
/**
91 92
 * Interruptible variant of poll().
 *
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
 * Waits for file descriptors I/O events, a timeout, a signal or a VLC I/O
 * interruption. Except for VLC I/O interruptions, this function behaves
 * just like the standard poll().
 *
 * @note This function is always a cancellation point (as poll()).
 * @see poll() manual page
 *
 * @param fds table of events to wait for
 * @param nfds number of entries in the table
 * @param timeout time to wait in milliseconds or -1 for infinite
 *
 * @return A strictly positive result represent the number of pending events.
 * 0 is returned if the time-out is reached without events.
 * -1 is returned if a VLC I/O interrupt occurs (and errno is set to EINTR)
 * or if an error occurs.
 */
VLC_API int vlc_poll_i11e(struct pollfd *, unsigned, int);

111 112 113 114 115
VLC_API ssize_t vlc_readv_i11e(int fd, struct iovec *, int);
VLC_API ssize_t vlc_writev_i11e(int fd, const struct iovec *, int);
VLC_API ssize_t vlc_read_i11e(int fd, void *, size_t);
VLC_API ssize_t vlc_write_i11e(int fd, const void *, size_t);

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
VLC_API ssize_t vlc_recvmsg_i11e(int fd, struct msghdr *, int flags);
VLC_API ssize_t vlc_sendmsg_i11e(int fd, const struct msghdr *, int flags);

VLC_API ssize_t vlc_recvfrom_i11e(int fd, void *, size_t, int flags,
                                struct sockaddr *, socklen_t *);
VLC_API ssize_t vlc_sendto_i11e(int fd, const void *, size_t, int flags,
                              const struct sockaddr *, socklen_t);

static inline ssize_t vlc_recv_i11e(int fd, void *buf, size_t len, int flags)
{
    return vlc_recvfrom_i11e(fd, buf, len, flags, NULL, NULL);
}

static inline
ssize_t vlc_send_i11e(int fd, const void *buf, size_t len, int flags)
{
    return vlc_sendto_i11e(fd, buf, len, flags, NULL, 0);
}

135 136
VLC_API int vlc_accept_i11e(int fd, struct sockaddr *, socklen_t *, bool);

137 138 139 140 141 142 143 144 145 146 147 148 149 150
/**
 * Registers a custom interrupt handler.
 *
 * Registers a custom callback as interrupt handler for the calling thread.
 * The callback must be unregistered with vlc_interrupt_unregister() before
 * thread termination and before any further callback registration.
 *
 * If the calling thread has no interruption context, this function has no
 * effects.
 */
VLC_API void vlc_interrupt_register(void (*cb)(void *), void *opaque);

VLC_API int vlc_interrupt_unregister(void);

151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
/**
 * @}
 * @defgroup interrupt_context Interrupt context signaling and manipulation
 * @{
 */
typedef struct vlc_interrupt vlc_interrupt_t;

/**
 * Creates an interruption context.
 */
VLC_API vlc_interrupt_t *vlc_interrupt_create(void) VLC_USED;

/**
 * Destroys an interrupt context.
 */
VLC_API void vlc_interrupt_destroy(vlc_interrupt_t *);

/**
 * Sets the interruption context for the calling thread.
 * @param newctx the interruption context to attach or NULL for none
 * @return the previous interruption context or NULL if none
 *
 * @note This function is not a cancellation point.
 * @warning A context can be attached to no more than one thread at a time.
 */
VLC_API vlc_interrupt_t *vlc_interrupt_set(vlc_interrupt_t *);

/**
179 180 181 182
 * Raises an interruption through a specified context.
 *
 * This is used to asynchronously wake a thread up while it is waiting on some
 * other events (typically I/O events).
183 184 185 186 187 188
 *
 * @note This function is thread-safe.
 * @note This function is not a cancellation point.
 */
VLC_API void vlc_interrupt_raise(vlc_interrupt_t *);

189
/**
190 191 192
 * Marks the interruption context as "killed".
 *
 * This is not reversible.
193 194 195 196
 */
VLC_API void vlc_interrupt_kill(vlc_interrupt_t *);

/**
197 198
 * Checks if the interruption context was "killed".
 *
199 200 201 202 203
 * Indicates whether the interruption context of the calling thread (if any)
 * was killed with vlc_interrupt_kill().
 */
VLC_API bool vlc_killed(void) VLC_USED;

204 205 206 207 208 209 210
/**
 * Enables forwarding of interruption.
 *
 * If an interruption is raised through the context of the calling thread,
 * it will be forwarded to the specified other context. This is used to cross
 * thread boundaries.
 *
211
 * If the calling thread has no interrupt context, this function does nothing.
212 213 214
 *
 * @param to context to forward to
 */
215 216
VLC_API void vlc_interrupt_forward_start(vlc_interrupt_t *to,
                                         void *data[2]);
217 218 219 220

/**
 * Undoes vlc_interrupt_forward_start().
 *
221
 * This function must be called after each successful call to
222 223 224 225 226 227 228 229 230 231 232 233 234
 * vlc_interrupt_forward_start() before any other interruptible call is made
 * in the same thread.
 *
 * If an interruption was raised against the context of the calling thread
 * (after the previous call to vlc_interrupt_forward_start()), it is dequeued.
 *
 * If the calling thread has no interrupt context, this function does nothing
 * and returns zero.
 *
 * @return 0 if no interrupt was raised, EINTR if an interrupt was raised
 */
VLC_API int vlc_interrupt_forward_stop(void *const data[2]);

235 236
/** @} @} */
#endif