## cothreads

cothreads — userspace threads

## Synopsis

    #include <gst/gst.h>

    struct      cothread_state;
    int         (*cothread_func)                (int argc,
                                                 char **argv);
    struct      cothread_context;
    #define     COTHREAD_STARTED
    #define     COTHREAD_DESTROYED
    cothread_context* cothread_context_init     (void);
    void        cothread_context_free           (cothread_context *ctx);
    gpointer    cothread_get_private            (cothread_state *cothread);
    void        cothread_set_private            (cothread_state *cothread,
                                                 gpointer data);
    cothread_state* cothread_create             (cothread_context *ctx);
    void        cothread_free                   (cothread_state *cothread);
    void        cothread_setfunc                (cothread_state *cothread,
                                                 cothread_func func,
                                                 int argc,
                                                 char **argv);
    void        cothread_stop                   (cothread_state *cothread);
    void        cothread_switch                 (cothread_state *cothread);
    gpointer    cothread_context_get_data       (cothread_state *cothread,
                                                 gchar *key);
    void        cothread_context_set_data       (cothread_state *cothread,
                                                 gchar *key,
                                                 gpointer data);
    void        cothread_lock                   (cothread_state *cothread);
    gboolean    cothread_trylock                (cothread_state *cothread);
    void        cothread_unlock                 (cothread_state *cothread);
    cothread_state* cothread_main               (cothread_context *ctx);
    cothread_state* cothread_current_main       (void);
    cothread_state* cothread_current            (void);

## Description

Cothreads are a simple user-space method for switching between subtasks. They're based on setjmp()/longjmp() in their current form.

Cothreads are used for loop-based elements that pull data instead of being fed with data. Cothreads are usually used by a GstScheduler.

## Details

### struct cothread_state

    struct cothread_state {

      cothread_context 	*ctx;
      int			 cothreadnum;
      gpointer		 priv;

      cothread_func		 func;
      int			 argc;
      char		       **argv;

      int			 flags;
      void			*sp;
      jmp_buf		 jmp;
      void			*stack_base;
      unsigned long		 stack_size;

      int			 magic_number;
    };

The cothread state structure

### cothread_func ()

    int         (*cothread_func)                (int argc,
                                                 char **argv);

the function that will be called when the cothread starts. The function prototype is like a main() function, so you can do whatever you want with it.

`argc` : | a main-like argument count
`argv` : | a main-like array of arguments
Returns : | a return code

### struct cothread_context

    struct cothread_context {

      GSList *              cothreads; /* contains all threads but main */
      cothread *            main;
      cothread *            current;
      GMutex *              mutex;
    };

The cothread context structure

### COTHREAD_STARTED

    #define COTHREAD_STARTED	0x01

Indicates the cothread is started.

### COTHREAD_DESTROYED

    #define COTHREAD_DESTROYED	0x02

Indicates the cothread is destroyed.

### cothread_context_init ()

    cothread_context* cothread_context_init     (void);

Create and initialize a new cothread context

Returns : | the new cothread context

### cothread_context_free ()

    void        cothread_context_free           (cothread_context *ctx);

Free the cothread context.

`ctx` : | the cothread context to free

### cothread_get_private ()

    gpointer    cothread_get_private            (cothread_state *cothread);

get the private data from the cothread

`cothread` : | the cothread state
Returns : | the private data of the cothread

### cothread_set_private ()

    void        cothread_set_private            (cothread_state *cothread,
                                                 gpointer data);

set private data for the cothread.

`cothread` : | the cothread state
`data` : | the data

### cothread_create ()

    cothread_state* cothread_create             (cothread_context *ctx);

Create a new cothread state in the given context

`ctx` : | the cothread context
Returns : | the new cothread state or NULL on error

### cothread_free ()

    void        cothread_free                   (cothread_state *cothread);

Free the given cothread state

`cothread` : | the cothread state

### cothread_setfunc ()

    void        cothread_setfunc                (cothread_state *cothread,
                                                 cothread_func func,
                                                 int argc,
                                                 char **argv);

Set the cothread function

`cothread` : | the cothread state
`func` : | the function to call
`argc` : | argument count for the cothread function
`argv` : | arguments for the cothread function

### cothread_stop ()

    void        cothread_stop                   (cothread_state *cothread);

Stop the cothread and reset the stack and program counter.

`cothread` : | the cothread to stop

### cothread_switch ()

    void        cothread_switch                 (cothread_state *cothread);

Switches to the given cothread state

`cothread` : | cothread state to switch to

### cothread_context_get_data ()

    gpointer    cothread_context_get_data       (cothread_state *cothread,
                                                 gchar *key);

get data from the cothread

`cothread` : | the cothread state
`key` : | a key for the data
Returns : | the data associated with the key

### cothread_context_set_data ()

    void        cothread_context_set_data       (cothread_state *cothread,
                                                 gchar *key,
                                                 gpointer data);

adds data to a cothread

`cothread` : | the cothread state
`key` : | a key for the data
`data` : | the data

### cothread_lock ()

    void        cothread_lock                   (cothread_state *cothread);

Locks the cothread state.

`cothread` : | cothread state to lock

### cothread_trylock ()

    gboolean    cothread_trylock                (cothread_state *cothread);

Try to lock the cothread state

`cothread` : | cothread state to try to lock
Returns : | TRUE if the cothread could be locked.

### cothread_unlock ()

    void        cothread_unlock                 (cothread_state *cothread);

Unlock the cothread state.

`cothread` : | cothread state to unlock

### cothread_main ()

    cothread_state* cothread_main               (cothread_context *ctx);

Gets the main thread.

`ctx` : | cothread context to find main cothread of.
Returns : | the cothread_state of the main (0th) cothread.

### cothread_current_main ()

    cothread_state* cothread_current_main       (void);

Get the main thread in the current GThread.

Returns : | the cothread_state of the main (0th) thread in the current GThread

### cothread_current ()

    cothread_state* cothread_current            (void);

Get the currenttly executing cothread

Returns : | the cothread_state of the current cothread

## See Also

GstScheduler