| Qore Programming Language - C/C++ Library 1.0.8

Classes | Macros | Typedefs | Functions | Variables
qore_thread.h File Reference
`#include <cstdio>`
`#include <pthread.h>`
`#include <functional>`
Include dependency graph for qore_thread.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
struct | q_user_tld
| data structure for user thread-local data More...
class | QoreForeignThreadHelper
| use this class to temporarily register and deregister a foreign thread to allow Qore code to be executed and the Qore library to be used from threads not created by the Qore library More...
class | ThreadCleanupList
| list of functions to be run when a thread ends; required for some external libraries that require explicit cleanup when a thread terminates More...

## Macros
#define | QFT_ERROR -1
| error when calling q_register_foreign_thread()
#define | QFT_OK 0
| OK response when calling q_register_foreign_thread()
#define | QFT_REGISTERED -2
| thread already registered when calling q_register_foreign_thread()

## Typedefs
typedef void(* | q_thread_t) (ExceptionSink *xsink, void *arg)
| pointer to a function that can be started with q_start_thread()
typedef void(* | qtdest_t) (void *)
| pointer to a qore thread destructor function
typedef void(* | qtrdest_t) (void *, ExceptionSink *)
| pointer to a qore thread resource destructor function

## Functions
DLLEXPORT bool | check_thread_resource (AbstractThreadResource *atr)
| check if a thread resouce has been saved More...
DLLEXPORT const AbstractQoreZoneInfo * | currentTZ ()
| returns the current local time zone, note that if 0 = UTC
DLLEXPORT QoreProgram * | getProgram ()
| returns the current QoreProgram
DLLEXPORT int | gettid () noexcept
DLLEXPORT bool | is_valid_qore_thread ()
| returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore More...
DLLEXPORT int | q_deregister_foreign_thread ()
| deregisters the current thread as a foreign thread More...
DLLEXPORT int | q_deregister_reserved_foreign_thread ()
| deregisters a foreign qore thread but retains the TID as reserved More...
DLLEXPORT void * | q_get_thread_local_data (int key)
| returns thread-local data More...
DLLEXPORT q_user_tld * | q_get_thread_local_data_all (int key)
| returns thread-local data More...
DLLEXPORT int | q_get_unique_thread_local_data_key ()
| returns a unique ID to use with thread_local_data APIs More...
DLLEXPORT int | q_gettid () noexcept
| returns the current TID number More...
DLLEXPORT int | q_register_foreign_thread ()
| registers the current thread as a Qore thread; returns QFT_OK (0) if the thread was successfully registered, QFT_ERROR (-1) if an error occurred, or QFT_REGISTERED (-2) if it was already registered More...
DLLEXPORT int | q_register_reserved_foreign_thread (int tid)
| registers a foreign qore thread as a Qore thread with a reserved TID More...
DLLEXPORT int | q_release_reserved_foreign_thread_id (int tid)
| releases a TID reserved with q_reserve_foreign_thread_id() More...
DLLEXPORT int | q_remove_thread_local_data (int key, q_user_tld &data, bool run_destructor=true)
| returns and removes thread-local data More...
DLLEXPORT int | q_reserve_foreign_thread_id ()
| reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation More...
DLLEXPORT void | q_save_thread_local_data (int key, void *data, q_thread_local_destructor destructor=nullptr)
| saves thread-local data More...
int | q_start_thread (ExceptionSink *xsink, q_thread_t f, void *arg=nullptr)
| starts a new thread with the given arguments, when the thread terminates, it deregisters itself More...
DLLEXPORT void * | q_swap_thread_local_data (int key, void *new_data, q_thread_local_destructor destructor=nullptr, bool run_destructor=true)
| swaps thread-local data More...
DLLEXPORT q_trid_t | qore_get_trid ()
| get a thread resource ID
DLLEXPORT int | remove_thread_resource (AbstractThreadResource *atr)
| remove the resource from the thread resource list for the current thread More...
DLLEXPORT int | remove_thread_resource (const ResolvedCallReferenceNode *rcr, ExceptionSink *xsink)
| remove the callable resource from the thread resource list for the current thread More...
DLLEXPORT void | set_thread_resource (AbstractThreadResource *atr)
| save a resource against a thread for thread resource handling More...
DLLEXPORT void | set_thread_resource (const ResolvedCallReferenceNode *rcr, const QoreValue arg)
| save a callable resource against a thread for thread resource handling More...

## Variables
DLLEXPORT ThreadCleanupList | tclist
| the interface to the thread cleanup list

## Detailed Description

Provides definitions relative to threading in Qore.

## Function Documentation

## ◆ check_thread_resource()

DLLEXPORT bool check_thread_resource | ( | AbstractThreadResource * | atr | ) |

check if a thread resouce has been saved

Parameters

  atr | thread resource id to check

Returns
  true if saved, false if not saved

## ◆ gettid()

DLLEXPORT int gettid | ( |  | ) |
| noexcept

Deprecated:
  due to symbol conflicts; use q_gettid() instead

## ◆ is_valid_qore_thread()

DLLEXPORT bool is_valid_qore_thread | ( |  | ) |

returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore

See also
  - QoreForeignThreadHelper
  - q_register_foreign_thread()
  - q_deregister_foreign_thread()

## ◆ q_deregister_foreign_thread()

DLLEXPORT int q_deregister_foreign_thread | ( |  | ) |

deregisters the current thread as a foreign thread

Returns
  0 if the foreign thread was deregistered, -1 if it was not registered or was not a foreign thread

See also
  - QoreForeignThreadHelper
  - q_register_foreign_thread()
  - is_valid_qore_thread();

Since
  Qore 0.8.7

## ◆ q_deregister_reserved_foreign_thread()

DLLEXPORT int q_deregister_reserved_foreign_thread | ( |  | ) |

deregisters a foreign qore thread but retains the TID as reserved

Returns
  0 for OK, -1 for error (TID invalid or not foreign)

Since
  Qore 0.8.7

## ◆ q_get_thread_local_data()

DLLEXPORT void* q_get_thread_local_data | ( | int | key | ) |

returns thread-local data

Note
  can only be called in a registered Qore thread

Since
  Qore 0.9.5

## ◆ q_get_thread_local_data_all()

DLLEXPORT q_user_tld* q_get_thread_local_data_all | ( | int | key | ) |

returns thread-local data

Parameters

  key | the key used to save the data

Returns
  nullptr if the data was not found, otherwise a pointer to the data structure holding the data

Note
  can only be called in a registered Qore thread

Since
  Qore 0.9.5

## ◆ q_get_unique_thread_local_data_key()

DLLEXPORT int q_get_unique_thread_local_data_key | ( |  | ) |

returns a unique ID to use with thread_local_data APIs

Since
  Qore 0.9.5

## ◆ q_gettid()

DLLEXPORT int q_gettid | ( |  | ) |
| noexcept

returns the current TID number

Since
  Qore 0.9.5.1

## ◆ q_register_foreign_thread()

DLLEXPORT int q_register_foreign_thread | ( |  | ) |

registers the current thread as a Qore thread; returns QFT_OK (0) if the thread was successfully registered, QFT_ERROR (-1) if an error occurred, or QFT_REGISTERED (-2) if it was already registered

call q_deregister_foreign_thread() when Qore functionality is no longer required; not calling q_deregister_foreign_thread() will cause a memory leak

Returns
  see Return Value Codes for q_register_foreign_thread() for return values

See also
  - QoreForeignThreadHelper
  - q_deregister_foreign_thread()
  - is_valid_qore_thread();

Since
  Qore 0.8.7

## ◆ q_register_reserved_foreign_thread()

DLLEXPORT int q_register_reserved_foreign_thread | ( | int | tid | ) |

registers a foreign qore thread as a Qore thread with a reserved TID

Parameters

  tid | the TID reserved with q_reserve_foreign_thread_id()

Returns
  0 for OK, -1 for error (TID invalid or not reserved)

Since
  Qore 0.8.7

## ◆ q_release_reserved_foreign_thread_id()

DLLEXPORT int q_release_reserved_foreign_thread_id | ( | int | tid | ) |

releases a TID reserved with q_reserve_foreign_thread_id()

Parameters

  tid | the TID reserved with q_reserve_foreign_thread_id()

Returns
  0 for OK, -1 for error (TID invalid or not reserved)

Since
  Qore 0.8.7

## ◆ q_remove_thread_local_data()

DLLEXPORT int q_remove_thread_local_data | ( | int | key,
|  | q_user_tld & | data,
|  | bool | run_destructor = `true`
| ) |  |

returns and removes thread-local data

Parameters

  key | the key used to save the data
  data | the data structure, if found (output variable)
  run_destructor | if true then the destructor is run when the data is removed; if false, it is not

Returns
  -1 if the data was not found, 0 if found and returned

Note
  can only be called in a registered Qore thread

Since
  Qore 0.9.5

## ◆ q_reserve_foreign_thread_id()

DLLEXPORT int q_reserve_foreign_thread_id | ( |  | ) |

reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation

Returns
  the TID reserved or -1 if an error occurred (thread table full)

Since
  Qore 0.8.7

## ◆ q_save_thread_local_data()

DLLEXPORT void q_save_thread_local_data | ( | int | key,
|  | void * | data,
|  | q_thread_local_destructor | destructor = `nullptr`
| ) |  |

saves thread-local data

can only be called in a registered Qore thread

Since
  Qore 0.9.5

## ◆ q_start_thread()

int q_start_thread | ( | ExceptionSink * | xsink,
|  | q_thread_t | f,
|  | void * | arg = `nullptr`
| ) |  |

starts a new thread with the given arguments, when the thread terminates, it deregisters itself

Parameters

  arg | the argument to the function
  f | the function to start in the new thread
  xsink | any errors starting the new thread will be raised here and cause -1 to be returned

Returns
  the new TID or -1 if an error occurred

Since
  Qore 0.8.8

## ◆ q_swap_thread_local_data()

DLLEXPORT void* q_swap_thread_local_data | ( | int | key,
|  | void * | new_data,
|  | q_thread_local_destructor | destructor = `nullptr`,
|  | bool | run_destructor = `true`
| ) |  |

swaps thread-local data

can only be called in a registered Qore thread

Since
  Qore 0.9.5

## ◆ remove_thread_resource() [1/2]

DLLEXPORT int remove_thread_resource | ( | AbstractThreadResource * | atr | ) |

remove the resource from the thread resource list for the current thread

Parameters

  atr | a pointer to the thread resource to remove

Returns
  0 if successful (resource was found and removed), -1 if the resource was not found

## ◆ remove_thread_resource() [2/2]

DLLEXPORT int remove_thread_resource | ( | const ResolvedCallReferenceNode * | rcr,
|  | ExceptionSink * | xsink
| ) |  |

remove the callable resource from the thread resource list for the current thread

Parameters

  rcr | a pointer to the thread resource to remove
  xsink | any Qore-language exceptions raised when dereferencing the callable object will be saved here

Returns
  0 if successful (resource was found and removed), -1 if the resource was not found

## ◆ set_thread_resource() [1/2]

DLLEXPORT void set_thread_resource | ( | AbstractThreadResource * | atr | ) |

save a resource against a thread for thread resource handling

Parameters

  atr | a pointer to the thread resource to save

## ◆ set_thread_resource() [2/2]

DLLEXPORT void set_thread_resource | ( | const ResolvedCallReferenceNode * | rcr,
|  | const QoreValue | arg
| ) |  |

save a callable resource against a thread for thread resource handling

Parameters

  rcr | a pointer to a callable node for thread resource handling
  arg | an argument to use when calling the thread resource handler