GstRTSPThreadPool

## GstRTSPThreadPool GstRTSPThreadPool — A pool of threads |

## Synopsis

    enum                GstRTSPThreadType;
    struct              GstRTSPThread;
    GstRTSPThread *     gst_rtsp_thread_new                 (GstRTSPThreadType type);
    GstRTSPThread *     gst_rtsp_thread_ref                 (GstRTSPThread *thread);
    void                gst_rtsp_thread_unref               (GstRTSPPermissions *thread);
    gboolean            gst_rtsp_thread_reuse               (GstRTSPThread *thread);
    void                gst_rtsp_thread_stop                (GstRTSPThread *thread);

    struct              GstRTSPThreadPool;
    struct              GstRTSPThreadPoolClass;
    GstRTSPThreadPool * gst_rtsp_thread_pool_new            (void);
    gint                gst_rtsp_thread_pool_get_max_threads
                                                            (GstRTSPThreadPool *pool);
    void                gst_rtsp_thread_pool_set_max_threads
                                                            (GstRTSPThreadPool *pool,
                                                             gint max_threads);
    GstRTSPThread *     gst_rtsp_thread_pool_get_thread     (GstRTSPThreadPool *pool,
                                                             GstRTSPThreadType type,
                                                             GstRTSPContext *ctx);
    void                gst_rtsp_thread_pool_cleanup        (void);

## Description

A GstRTSPThreadPool manages reusable threads for various server tasks. Currently the defined thread types can be found in GstRTSPThreadType.

Threads of type GST_RTSP_THREAD_TYPE_CLIENT are used to handle requests from a connected client. With `gst_rtsp_thread_pool_get_max_threads()` a maximum number of threads can be set after which the pool will start to reuse the same thread for multiple clients.

Threads of type GST_RTSP_THREAD_TYPE_MEDIA will be used to perform the state changes of the media pipelines and handle its bus messages.

`gst_rtsp_thread_pool_get_thread()` can be used to create a GstRTSPThread object of the right type. The thread object contains a mainloop and context that run in a seperate thread and can be used to attached sources to.

`gst_rtsp_thread_reuse()` can be used to reuse a thread for multiple purposes. If all `gst_rtsp_thread_reuse()` calls are matched with a `gst_rtsp_thread_stop()` call, the mainloop will be quit and the thread will stop.

To configure the threads, a subclass of this object should be made and the virtual methods should be overriden to implement the desired functionality.

Last reviewed on 2013-07-11 (1.0.0)

## Details

### enum GstRTSPThreadType

    typedef enum {
      GST_RTSP_THREAD_TYPE_CLIENT,
      GST_RTSP_THREAD_TYPE_MEDIA
    } GstRTSPThreadType;

Different thread types

`GST_RTSP_THREAD_TYPE_CLIENT` | a thread to handle the client communication
`GST_RTSP_THREAD_TYPE_MEDIA` | a thread to handle media

### struct GstRTSPThread

    struct GstRTSPThread {
      GstMiniObject mini_object;

      GstRTSPThreadType type;
      GMainContext *context;
      GMainLoop *loop;
    };

Structure holding info about a mainloop running in a thread

GstMiniObject `mini_object`; | parent GstMiniObject
GstRTSPThreadType `type`; | the thread type
GMainContext *`context`; | a GMainContext
GMainLoop *`loop`; | a GMainLoop

### gst_rtsp_thread_new ()

    GstRTSPThread *     gst_rtsp_thread_new                 (GstRTSPThreadType type);

Create a new thread object that can run a mainloop.

`type` : | the thread type
Returns : | a GstRTSPThread.

### gst_rtsp_thread_ref ()

    GstRTSPThread *     gst_rtsp_thread_ref                 (GstRTSPThread *thread);

Increase the refcount of this thread.

`thread` : | The thread to refcount
Returns : | `thread` (for convenience when doing assignments). [transfer full]

### gst_rtsp_thread_unref ()

    void                gst_rtsp_thread_unref               (GstRTSPPermissions *thread);

Decrease the refcount of an thread, freeing it if the refcount reaches 0.

`thread` : | the thread to refcount. [transfer full]

### gst_rtsp_thread_reuse ()

    gboolean            gst_rtsp_thread_reuse               (GstRTSPThread *thread);

Reuse the mainloop of `thread`

`thread` : | a GstRTSPThread
Returns : | `TRUE` if the mainloop could be reused

### gst_rtsp_thread_stop ()

    void                gst_rtsp_thread_stop                (GstRTSPThread *thread);

Stop and unref `thread`. When no threads are using the mainloop, the thread will be stopped and the final ref to `thread` will be released.

`thread` : | a GstRTSPThread. [transfer full]

### struct GstRTSPThreadPool

    struct GstRTSPThreadPool {
      GObject       parent;
    };

The thread pool structure.

### struct GstRTSPThreadPoolClass

    struct GstRTSPThreadPoolClass {
      GObjectClass  parent_class;

      GThreadPool *pool;

      GstRTSPThread * (*get_thread)        (GstRTSPThreadPool *pool,
                                            GstRTSPThreadType type,
                                            GstRTSPContext *ctx);
      void            (*configure_thread)  (GstRTSPThreadPool *pool,
                                            GstRTSPThread * thread,
                                            GstRTSPContext *ctx);

      void            (*thread_enter)      (GstRTSPThreadPool *pool,
                                            GstRTSPThread *thread);
      void            (*thread_leave)      (GstRTSPThreadPool *pool,
                                            GstRTSPThread *thread);
    };

Class for managing threads.

GObjectClass `parent_class`; |
GThreadPool *`pool`; | a GThreadPool used internally
`get_thread` () | this function should make or reuse an existing thread that runs a mainloop.
`configure_thread` () | configure a thread object. this vmethod is called when a new thread has been created and should be configured.
`thread_enter` () | called from the thread when it is entered
`thread_leave` () | called from the thread when it is left

### gst_rtsp_thread_pool_new ()

    GstRTSPThreadPool * gst_rtsp_thread_pool_new            (void);

Create a new GstRTSPThreadPool instance.

Returns : | a new GstRTSPThreadPool

### gst_rtsp_thread_pool_get_max_threads ()

    gint                gst_rtsp_thread_pool_get_max_threads
                                                            (GstRTSPThreadPool *pool);

Get the maximum number of threads used for client connections. See `gst_rtsp_thread_pool_set_max_threads()`.

`pool` : | a GstRTSPThreadPool
Returns : | the maximum number of threads.

### gst_rtsp_thread_pool_set_max_threads ()

    void                gst_rtsp_thread_pool_set_max_threads
                                                            (GstRTSPThreadPool *pool,
                                                             gint max_threads);

Set the maximum threads used by the pool to handle client requests. A value of 0 will use the pool mainloop, a value of -1 will use an unlimited number of threads.

`pool` : | a GstRTSPThreadPool
`max_threads` : | maximum threads

### gst_rtsp_thread_pool_get_thread ()

    GstRTSPThread *     gst_rtsp_thread_pool_get_thread     (GstRTSPThreadPool *pool,
                                                             GstRTSPThreadType type,
                                                             GstRTSPContext *ctx);

Get a new GstRTSPThread for `type` and `ctx`.

`pool` : | a GstRTSPThreadPool
`type` : | the GstRTSPThreadType
`ctx` : | a GstRTSPContext
Returns : | a new GstRTSPThread, `gst_rtsp_thread_stop()` after usage

### gst_rtsp_thread_pool_cleanup ()

    void                gst_rtsp_thread_pool_cleanup        (void);

Wait for all tasks to be stopped and free all allocated resources. This is mainly used in test suites to ensure proper cleanup of internal data structures.

## See Also

GstRTSPMedia, GstRTSPClient