1 /*****************************************************************************
2 * vlc_cxx_helpers.hpp: C++ helpers
3 *****************************************************************************
4 * Copyright (C) 1998-2018 VLC authors and VideoLAN
6 * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
23 #ifndef VLC_CXX_HELPERS_HPP
24 #define VLC_CXX_HELPERS_HPP
26 /******************************************************************************
27 * C++ memory management helpers
28 ******************************************************************************/
34 #include <type_traits>
37 // Ensure we can use vlc_sem_wait_i11e. We can't declare different versions
38 // of the semaphore helper based on vlc_interrupt inclusion, as it would
40 # include <vlc_interrupt.h>
48 // This helpers need static linkage to avoid their signature to change when
49 // building as C++17 (noexcept becomes part of the function signature stating there)
51 // Wraps a pointer with a custom releaser
52 // ex: auto ptr = vlc_wrap_cptr( input_item, &input_item_Release );
55 /// Wraps a C pointer into a std::unique_ptr
57 /// This will convert a C pointer of type T to a std::unique_ptr<T, R> where
58 /// T is the pointee type, and R is an arbitrary releaser type.
60 /// ptr will be automatically released by calling r( ptr ) when falling out of
61 /// scope (whether by returning of by throwing an exception
63 /// @param ptr a C pointer
64 /// @param r An instance of a Callable type, that will be invoked with ptr
65 /// as its first and only parameter.
66 template <typename T
, typename Releaser
>
67 inline auto wrap_cptr( T
* ptr
, Releaser
&& r
) noexcept
68 -> std::unique_ptr
<T
, typename
std::decay
<decltype( r
)>::type
>
70 return std::unique_ptr
<T
, typename
std::decay
<decltype( r
)>::type
>{
71 ptr
, std::forward
<Releaser
>( r
)
76 /// Wraps a C pointer into a std::unique_ptr
78 /// This will convert a C pointer to an array of type T to a
79 /// std::unique_ptr<T[], R> where T is the pointee type, and R is an arbitrary
82 /// ptr will be automatically released by calling r( ptr ) when falling out of
83 /// scope (whether by returning of by throwing an exception
85 /// This function is equivalent to wrap_cptr, except that the returned
86 /// unique_ptr provides an operator[] for array access instead of operator* and
89 /// @param ptr a C pointer
90 /// @param r An instance of a Callable type, that will be invoked with ptr
91 /// as its first and only parameter.
92 template <typename T
, typename Releaser
>
93 inline auto wrap_carray( T
* ptr
, Releaser
&& r
) noexcept
94 -> std::unique_ptr
<T
[], typename
std::decay
<decltype( r
)>::type
>
96 return std::unique_ptr
<T
[], typename
std::decay
<decltype( r
)>::type
>{
97 ptr
, std::forward
<Releaser
>( r
)
102 /// Wraps a C pointer into a std::unique_ptr
104 /// This is a convenience wrapper that will use free() as its releaser
106 template <typename T
>
107 inline std::unique_ptr
<T
, void (*)(void*)> wrap_cptr( T
* ptr
) noexcept
109 return wrap_cptr( ptr
, &free
);
113 /// Wraps a C pointer into a std::unique_ptr
115 /// This is a convenience wrapper that will use free() as its releaser
117 template <typename T
>
118 inline std::unique_ptr
<T
[], void (*)(void*)> wrap_carray( T
* ptr
) noexcept
120 return wrap_carray( ptr
, &free
);
123 } // anonymous namespace
126 /// Wraps a C shared resource having associated Hold() and Release() functions
128 /// This is a RAII wrapper for C shared resources (which are manually managed by
129 /// calling explicitly their Hold() and Release() functions).
131 /// The Hold() and Release() functions must accept exactly one parameter having
132 /// type T* (the raw pointer type). Their return type is irrelevant.
134 /// To create a new shared resource wrapper type for my_type_t, simply declare:
136 /// using MyTypePtr =
137 /// vlc_shared_data_ptr_type(my_type_t, my_type_Hold, my_type_Release);
139 /// Then use it to wrap a raw C pointer:
141 /// my_type_t *raw_ptr = /* ... */;
142 /// MyTypePtr ptr(raw_ptr);
144 // In C++17, the template declaration could be replaced by:
145 // template<typename T, auto HOLD, auto RELEASE>
146 template <typename T
, typename H
, typename R
, H HOLD
, R RELEASE
>
147 class vlc_shared_data_ptr
{
151 /* default implicit constructor */
152 vlc_shared_data_ptr() = default;
155 * Wrap a shared resource.
157 * If the pointer is not nullptr, and hold is true, then the resource is
158 * hold (the caller shared ownership is preserved).
159 * If hold is false, then the caller transfers the ownership to this
162 * \param ptr the raw pointer (can be nullptr)
163 * \param hold whether the resource must be hold
165 explicit vlc_shared_data_ptr(T
*ptr
, bool hold
= true)
172 vlc_shared_data_ptr(const vlc_shared_data_ptr
&other
)
173 : vlc_shared_data_ptr(other
.ptr
) {}
175 vlc_shared_data_ptr(vlc_shared_data_ptr
&&other
) noexcept
181 ~vlc_shared_data_ptr()
187 vlc_shared_data_ptr
&operator=(const vlc_shared_data_ptr
&other
)
189 reset(other
.ptr
, true);
193 vlc_shared_data_ptr
&operator=(vlc_shared_data_ptr
&&other
) noexcept
195 reset(other
.ptr
, false);
200 bool operator==(const vlc_shared_data_ptr
&other
) const
202 return ptr
== other
.ptr
;
205 bool operator==(std::nullptr_t
) const noexcept
207 return ptr
== nullptr;
210 bool operator!=(const vlc_shared_data_ptr
&other
) const
212 return !(*this == other
);
215 bool operator!=(std::nullptr_t
) const noexcept
217 return ptr
!= nullptr;
220 explicit operator bool() const
230 T
*operator->() const
241 * Reset the shared resource.
243 * ptr.reset(rawptr, hold);
245 * is semantically equivalent to:
247 * ptr = vlc_shared_data_ptr<...>(rawptr, hold);
249 * If the pointer is not nullptr, and hold is true, then the resource is
250 * hold (the caller shared ownership is preserved).
251 * If hold is false, then the caller transfers the ownership to this
254 * \param ptr the raw pointer (can be nullptr)
255 * \param hold whether the resource must be hold
257 void reset(T
*newptr
= nullptr, bool hold
= true)
267 // useful due to the unnecessarily complex template declaration before C++17
268 #define vlc_shared_data_ptr_type(type, hold, release) \
269 ::vlc::vlc_shared_data_ptr<type, decltype(&hold), decltype(&release), \
272 #ifdef VLC_THREADS_H_
282 vlc_mutex_init( &m_mutex
);
285 mutex( const mutex
& ) = delete;
286 mutex
& operator=( const mutex
& ) = delete;
287 mutex( mutex
&& ) = delete;
288 mutex
& operator=( mutex
&& ) = delete;
292 vlc_mutex_lock( &m_mutex
);
294 void unlock() noexcept
296 vlc_mutex_unlock( &m_mutex
);
301 friend class condition_variable
;
302 friend class mutex_locker
;
305 class condition_variable
308 condition_variable() noexcept
310 vlc_cond_init( &m_cond
);
312 void signal() noexcept
314 vlc_cond_signal( &m_cond
);
316 void broadcast() noexcept
318 vlc_cond_broadcast( &m_cond
);
320 void wait( mutex
& mutex
) noexcept
322 vlc_cond_wait( &m_cond
, &mutex
.m_mutex
);
324 int timedwait( mutex
& mutex
, vlc_tick_t deadline
) noexcept
326 return vlc_cond_timedwait( &m_cond
, &mutex
.m_mutex
, deadline
);
336 mutex_locker( vlc_mutex_t
* m
) noexcept
339 vlc_mutex_lock( m_mutex
);
341 mutex_locker( mutex
& m
) noexcept
342 : mutex_locker( &m
.m_mutex
)
347 vlc_mutex_unlock( m_mutex
);
349 mutex_locker( const mutex_locker
& ) = delete;
350 mutex_locker
& operator=( const mutex_locker
& ) = delete;
351 mutex_locker( mutex_locker
&& ) = delete;
352 mutex_locker
& operator=( mutex_locker
&& ) = delete;
355 vlc_mutex_t
* m_mutex
;
363 vlc_sem_init( &m_sem
, 0 );
365 semaphore( unsigned int count
) noexcept
367 vlc_sem_init( &m_sem
, count
);
373 semaphore( const semaphore
& ) = delete;
374 semaphore
& operator=( const semaphore
& ) = delete;
375 semaphore( semaphore
&& ) = delete;
376 semaphore
& operator=( semaphore
&& ) = delete;
380 return vlc_sem_post( &m_sem
);
384 vlc_sem_wait( &m_sem
);
387 int wait_i11e() noexcept
389 return vlc_sem_wait_i11e( &m_sem
);
398 #endif // VLC_THREADS_H_
404 #endif // VLC_CXX_HELPERS_HPP