Qore Programming Language: include/qore/qore_thread.h File Reference

Qore Programming Language 0.8.11

- Main Page
- Related Pages
- Modules
- Classes
- Files

- File List
- File Members

All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Classes | Macros | Typedefs | Functions | Variables
qore_thread.h File Reference

### (6585)

`#include <stdio.h>`
`#include <pthread.h>`
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
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 ()
| returns the current TID number
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 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_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...
int | q_start_thread (ExceptionSink *xsink, q_thread_t f, void *arg=0)
| starts a new thread with the given arguments, when the thread terminates, it deregisters itself 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 void | set_thread_resource (AbstractThreadResource *atr)
| save a 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

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

check if a thread resouce has been saved

Parameters

  trid | thread resource id to check

Returns
  true if saved, false if not saved

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()

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

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

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

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

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

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

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

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

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

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