2012-10-18 22:47:33 -07:00
|
|
|
/* EINA - EFL data type library
|
|
|
|
* Copyright (C) 2012 Cedric Bail
|
|
|
|
*
|
|
|
|
* This library 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 library 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 library;
|
|
|
|
* if not, see <http://www.gnu.org/licenses/>.
|
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef EINA_THREAD_H_
|
|
|
|
#define EINA_THREAD_H_
|
|
|
|
|
|
|
|
#include "eina_config.h"
|
|
|
|
#include "eina_types.h"
|
|
|
|
#include "eina_error.h"
|
|
|
|
|
2015-01-30 01:49:55 -08:00
|
|
|
#include <stdint.h>
|
|
|
|
|
2012-10-18 22:47:33 -07:00
|
|
|
/**
|
|
|
|
* @addtogroup Eina_Tools_Group Tools
|
|
|
|
*
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @defgroup Eina_Thread_Group Thread
|
|
|
|
*
|
2018-07-12 00:27:15 -07:00
|
|
|
* Abstracts platform threads, providing a uniform API. It's modeled
|
2012-12-31 09:26:33 -08:00
|
|
|
* after POSIX THREADS (pthreads), on Linux they are almost 1:1
|
|
|
|
* mapping.
|
|
|
|
*
|
|
|
|
* @see @ref Eina_Lock_Group for mutex/locking abstraction.
|
|
|
|
*
|
|
|
|
* @since 1.8
|
2012-10-18 22:47:33 -07:00
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2014-10-03 02:36:38 -07:00
|
|
|
/**
|
|
|
|
* @typedef Eina_Thread
|
|
|
|
* Type for a generic thread.
|
|
|
|
*/
|
2015-01-30 01:49:55 -08:00
|
|
|
typedef uintptr_t Eina_Thread;
|
2012-10-18 22:47:33 -07:00
|
|
|
|
2014-10-03 02:36:38 -07:00
|
|
|
/**
|
|
|
|
* @typedef Eina_Thread_Cb
|
|
|
|
* Type for the definition of a thread callback function
|
|
|
|
*/
|
2012-10-18 22:47:33 -07:00
|
|
|
typedef void *(*Eina_Thread_Cb)(void *data, Eina_Thread t);
|
|
|
|
|
2014-10-03 02:36:38 -07:00
|
|
|
/**
|
2016-12-20 16:06:20 -08:00
|
|
|
* @typedef Eina_Thread_Priority
|
2014-10-03 02:36:38 -07:00
|
|
|
* Type to enumerate different thread priorities
|
|
|
|
*/
|
2012-10-18 22:47:33 -07:00
|
|
|
typedef enum _Eina_Thread_Priority
|
|
|
|
{
|
|
|
|
EINA_THREAD_URGENT,
|
|
|
|
EINA_THREAD_NORMAL,
|
|
|
|
EINA_THREAD_BACKGROUND,
|
|
|
|
EINA_THREAD_IDLE
|
|
|
|
} Eina_Thread_Priority;
|
|
|
|
|
2012-12-31 09:26:33 -08:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Returns identifier of the current thread.
|
2012-12-31 09:26:33 -08:00
|
|
|
* @return identifier of current thread.
|
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Checks if two thread identifiers are the same.
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] t1 first thread identifier to compare.
|
|
|
|
* @param[in] t2 second thread identifier to compare.
|
2012-12-31 09:26:33 -08:00
|
|
|
* @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise.
|
|
|
|
* @since 1.8
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Creates a new thread, setting its priority and affinity.
|
2012-12-31 09:26:33 -08:00
|
|
|
*
|
2017-10-17 10:54:15 -07:00
|
|
|
* @param[out] t where to return the thread identifier. Must @b not be @c NULL.
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] prio thread priority to use, usually EINA_THREAD_BACKGROUND
|
|
|
|
* @param[in] affinity thread affinity to use. To not set affinity use @c -1.
|
|
|
|
* @param[in] func function to run in the thread. Must @b not be @c NULL.
|
|
|
|
* @param[in] data context data to provide to @a func as first argument.
|
2012-12-31 09:26:33 -08:00
|
|
|
* @return #EINA_TRUE if thread was created, #EINA_FALSE on errors.
|
|
|
|
* @since 1.8
|
|
|
|
*/
|
2012-10-18 22:47:33 -07:00
|
|
|
EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
|
2012-10-19 00:13:08 -07:00
|
|
|
Eina_Thread_Priority prio, int affinity,
|
2012-12-31 09:26:33 -08:00
|
|
|
Eina_Thread_Cb func, const void *data) EINA_ARG_NONNULL(1, 4) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief The return value of eina_thread_join() if it was canceled with
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* eina_thread_cancel().
|
|
|
|
*
|
|
|
|
* A thread must be explicitly flagged as cancellable with
|
|
|
|
* eina_thread_cancellable_set(), by default it's not and this value
|
|
|
|
* shouldn't be returned.
|
|
|
|
*
|
|
|
|
* @see eina_thread_join()
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
EAPI extern const void *EINA_THREAD_JOIN_CANCELED;
|
|
|
|
|
2012-12-31 09:26:33 -08:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Joins a currently running thread, waiting until it finishes.
|
2012-12-31 09:26:33 -08:00
|
|
|
*
|
|
|
|
* This function will block the current thread until @a t
|
|
|
|
* finishes. The returned value is the one returned by @a t @c func()
|
|
|
|
* and may be @c NULL on errors. See @ref Eina_Error_Group to identify
|
|
|
|
* problems.
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] t thread identifier to wait.
|
2012-12-31 09:26:33 -08:00
|
|
|
* @return value returned by @a t creation function @c func() or
|
|
|
|
* @c NULL on errors. Check error with @ref Eina_Error_Group.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* If the thread was canceled, it will return
|
|
|
|
* EINA_THREAD_JOIN_CANCELED.
|
2012-12-31 09:26:33 -08:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
2012-10-18 22:47:33 -07:00
|
|
|
EAPI void *eina_thread_join(Eina_Thread t);
|
|
|
|
|
2015-09-08 20:45:47 -07:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Sets the name of a given thread for debugging purposes.
|
2015-09-08 20:45:47 -07:00
|
|
|
*
|
|
|
|
* This maps to the pthread_setname_np() GNU extension or similar
|
|
|
|
* if available. The name may be limited in size (possibly 16
|
2017-02-19 22:18:21 -08:00
|
|
|
* characters including the null byte terminator). This is useful
|
2015-09-08 20:45:47 -07:00
|
|
|
* for debugging to name a thread so external tools can display a
|
|
|
|
* meaningful name attached to the thread.
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] t thread to set the name of
|
|
|
|
* @param[in] name a string to name the thread - this cannot be NULL
|
2015-09-08 20:45:47 -07:00
|
|
|
* @return EINA_TRUE if it succeeds in setting the name or EINA_FALSE
|
|
|
|
* otherwise.
|
|
|
|
* @since 1.16
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
|
|
|
|
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Attempts to cancel a running thread.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
*
|
|
|
|
* This function sends a cancellation request to the thread, however
|
|
|
|
* that request is only fulfilled if the thread is cancellable
|
2018-07-12 00:27:15 -07:00
|
|
|
* (eina_thread_cancellable_set() with EINA_TRUE as first parameter)
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* and it will wait for a cancellation point, be
|
|
|
|
* eina_thread_cancel_checkpoint() or some syscall as defined in
|
|
|
|
* man:pthreads(7).
|
|
|
|
*
|
|
|
|
* A thread that was canceled will return EINA_THREAD_JOIN_CANCELED
|
|
|
|
* when eina_thread_join() is called.
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] t Thread to cancel.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
*
|
|
|
|
* @return EINA_FALSE if thread was not running, EINA_TRUE
|
|
|
|
* otherwise. Note that if a thread is not cancellable and it
|
|
|
|
* is running, this function will return EINA_TRUE!
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);
|
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Enables or disables if the current thread can be canceled.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
*
|
|
|
|
* By default eina_thread_create() will return a thread with
|
|
|
|
* cancellation disabled. One can enable the cancellation by using
|
|
|
|
* EINA_TRUE in @a cancellable.
|
|
|
|
*
|
|
|
|
* Eina threads follow pthread_setcanceltype()
|
|
|
|
* PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait
|
|
|
|
* for a cancellation point, usually a syscall defined in
|
|
|
|
* man:pthreads(7) or an explicit cancellation point defined with
|
|
|
|
* eina_thread_cancel_checkpoint().
|
|
|
|
*
|
|
|
|
* In order to provide cleanup around critical blocks use
|
|
|
|
* EINA_THREAD_CLEANUP_PUSH() and EINA_THREAD_CLEANUP_POP() macros
|
|
|
|
* (which maps to pthread_cleanup_push() and pthread_cleanup_pop()),
|
|
|
|
* or the helper function eina_thread_cancellable_run() which does the
|
|
|
|
* pair for you.
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] cancellable If EINA_TRUE, this thread will be accept
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* cancellation requests. If EINA_FALSE -- the default, it will
|
|
|
|
* ignore cancellation requests.
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] was_cancellable If non-NULL, will return the previous state,
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* shall you want to restore.
|
|
|
|
*
|
|
|
|
* @return EINA_TRUE if it succeeds in setting the cancellable state
|
|
|
|
* or EINA_FALSE otherwise.
|
|
|
|
*
|
|
|
|
* @see eina_thread_cancel_checkpoint()
|
|
|
|
* @see EINA_THREAD_CLEANUP_PUSH()
|
|
|
|
* @see EINA_THREAD_CLEANUP_POP()
|
|
|
|
* @see eina_thread_cancellable_run()
|
|
|
|
* @see eina_thread_cancel()
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
EAPI Eina_Bool eina_thread_cancellable_set(Eina_Bool cancellable, Eina_Bool *was_cancellable);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* If the current thread is cancellable, this introduces a
|
|
|
|
* cancellation check point. Otherwise it's a no-operation.
|
|
|
|
*
|
|
|
|
* Eina threads follow pthread_setcanceltype()
|
|
|
|
* PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait
|
|
|
|
* for a cancellation point, usually a syscall defined in
|
|
|
|
* man:pthreads(7) or an explicit cancellation point defined with this
|
|
|
|
* function.
|
|
|
|
*
|
|
|
|
* @see eina_thread_cancel_checkpoint()
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
EAPI void eina_thread_cancel_checkpoint(void);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @def EINA_THREAD_CLEANUP_PUSH(cleanup, data)
|
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Pushes a cleanup function to be executed when the thread is
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* canceled.
|
|
|
|
*
|
|
|
|
* This macro will schedule a function cleanup(data) to be executed if
|
|
|
|
* the thread is canceled with eina_thread_cancel() and the thread
|
|
|
|
* was previously marked as cancellable with
|
|
|
|
* eina_thread_cancellable_set().
|
|
|
|
*
|
|
|
|
* It @b must be paired with EINA_THREAD_CLEANUP_POP() in the same
|
|
|
|
* code block as they will expand to do {} while ()!
|
|
|
|
*
|
|
|
|
* The cleanup function may also be executed if
|
|
|
|
* EINA_THREAD_CLEANUP_POP(EINA_TRUE) is used.
|
|
|
|
*
|
|
|
|
* @note If the block within EINA_THREAD_CLEANUP_PUSH() and
|
|
|
|
* EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will
|
|
|
|
* @b not be executed! To avoid problems prefer to use
|
|
|
|
* eina_thread_cancellable_run()!
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] cleanup The function to execute on cancellation.
|
|
|
|
* @param[in] data The context to give to cleanup function.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
*
|
|
|
|
* @see eina_thread_cancellable_run()
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
#define EINA_THREAD_CLEANUP_PUSH(cleanup, data) \
|
|
|
|
pthread_cleanup_push(cleanup, data)
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @def EINA_THREAD_CLEANUP_POP(exec_cleanup)
|
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Pops a cleanup function to be executed when the thread is
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* canceled.
|
|
|
|
*
|
|
|
|
* This macro will remove a previously pushed cleanup function, thus
|
|
|
|
* if the thread is canceled with eina_thread_cancel() and the thread
|
|
|
|
* was previously marked as cancellable with
|
|
|
|
* eina_thread_cancellable_set(), that cleanup won't be executed
|
|
|
|
* anymore.
|
|
|
|
*
|
|
|
|
* It @b must be paired with EINA_THREAD_CLEANUP_PUSH() in the same
|
|
|
|
* code block as they will expand to do {} while ()!
|
|
|
|
*
|
|
|
|
* @note If the block within EINA_THREAD_CLEANUP_PUSH() and
|
|
|
|
* EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will
|
|
|
|
* @b not be executed even if exec_cleanup is EINA_TRUE! To
|
|
|
|
* avoid problems prefer to use eina_thread_cancellable_run()!
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] exec_cleanup if EINA_TRUE, the function registered with
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* EINA_THREAD_CLEANUP_PUSH() will be executed.
|
|
|
|
*
|
|
|
|
* @see eina_thread_cancellable_run()
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
#define EINA_THREAD_CLEANUP_POP(exec_cleanup) \
|
|
|
|
pthread_cleanup_pop(exec_cleanup)
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Thread_Cancellable_Run_Cb
|
|
|
|
* Type for the definition of a cancellable callback to run.
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
|
|
|
typedef void *(*Eina_Thread_Cancellable_Run_Cb)(void *data);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* This function will setup cleanup callback, turn the thread
|
|
|
|
* cancellable, execute the given callback, reset the cancellable
|
|
|
|
* state to its old value, run the cleanup callback and then return
|
|
|
|
* the callback return value.
|
|
|
|
*
|
|
|
|
* @note cleanup_cb is configured @b before the thread is made
|
|
|
|
* cancellable, thus it @b will be executed while @a cb may not
|
|
|
|
* in the case the thread was already canceled and that was
|
|
|
|
* pending.
|
|
|
|
*
|
2017-11-12 19:04:59 -08:00
|
|
|
* This helper does exactly the following code. Should you need a
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* slightly different behavior, use the base calls yourself.
|
|
|
|
*
|
|
|
|
* @code
|
|
|
|
* Eina_Bool old = EINA_FALSE;
|
|
|
|
* void *ret;
|
|
|
|
*
|
|
|
|
* EINA_THREAD_CLEANUP_PUSH(cleanup_cb, data);
|
|
|
|
* eina_thread_cancellable_set(EINA_TRUE, &old); // is a cancellation point
|
|
|
|
* ret = cb(data); // may not run if was previously canceled
|
|
|
|
* EINA_THREAD_CLEANUP_POP(EINA_TRUE);
|
|
|
|
* eina_thread_cancellable_set(old, NULL);
|
|
|
|
* return ret;
|
|
|
|
* @endcode
|
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] cb a cancellable callback to possibly run. The callback @b
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* may not be executed if the thread had a pending cancellation
|
|
|
|
* request. During its execution the callback may be canceled
|
|
|
|
* at explicit cancellation points using
|
|
|
|
* eina_thread_cancel_checkpoint(), as well as some syscalls
|
|
|
|
* defined in man:pthreads(7).
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] cleanup_cb a cleanup callback to be executed regardless of
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
* the thread being canceled or not. This function will be
|
|
|
|
* executed even if @a cb wasn't.
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] data context to give to both @a cb and @a cleanup_cb.
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
*
|
|
|
|
* @return the return value of @a cb. If the thread was canceled,
|
|
|
|
* this function will not return.
|
|
|
|
*
|
|
|
|
* @since 1.19
|
|
|
|
*/
|
2016-11-15 10:59:54 -08:00
|
|
|
EAPI void *eina_thread_cancellable_run(Eina_Thread_Cancellable_Run_Cb cb, Eina_Free_Cb cleanup_cb, void *data);
|
eina/ecore: allow threads to be canceled, use in ecore_con.
As discussed in the mailing list, many people will use worker threads
to execute blocking syscalls and mandating ecore_thread_check() for
voluntary preemption reduces the ecore_thread usefulness a lot.
A clear example is ecore_con usage of connect() and getaddrinfo() in
threads. If the connect timeout expires, the thread will be cancelled,
but it was blocked on syscalls and they will hang around for long
time. If the application exits, ecore will print an error saying it
can SEGV.
Then enable access to pthread_setcancelstate(PTHREAD_CANCEL_ENABLE)
via eina_thread_cancellable_set(EINA_TRUE), to pthread_cancel() via
eina_thread_cancel(), to pthread_cleanup_push()/pthread_cleanup_pop()
via EINA_THREAD_CLEANUP_PUSH()/EINA_THREAD_CLEANUP_POP() and so on.
Ecore threads will enforce non-cancellable threads on its own code,
but the user may decide to enable that and allow cancellation, that's
not an issue since ecore_thread now plays well and use cleanup
functions.
Ecore con connect/resolve make use of that and enable cancellable
state, efl_net_dialer_tcp benefits a lot from that.
A good comparison of the benefit is to run:
./src/examples/ecore/efl_io_copier_example tcp://google.com:1234 :stdout:
before and after. It will timeout after 30s and with this patch the
thread is gone, no ecore error is printed about possible SEGV.
2016-09-13 21:38:58 -07:00
|
|
|
|
2012-10-18 22:47:33 -07:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
|
|
|
#endif
|