kore-doc

The kore documentation found under https://docs.kore.io/
Commits | Files | Refs | README | git clone https://git.kore.io/kore-doc.git

tasks.md (3816B)



      1 # Tasks
      2 
      3 The tasks API in Kore allows you to create background tasks which are scheduled over OS threads.
      4 
      5 Background tasks can communicate with the main thread via a socket pair.
      6 
      7 Kore must be built with TASKS=1 in order to use this API.
      8 
      9 ## Index
     10 
     11 * [kore\_task\_create](#create)
     12 * [kore\_task\_run](#run)
     13 * [kore\_task\_bind\_request](#bindrequest)
     14 * [kore\_task\_bind\_callback](#bindcallback)
     15 * [kore\_task\_destroy](#destroy)
     16 * [kore\_task\_finished](#finished)
     17 * [kore\_task\_channel\_write](#write)
     18 * [kore\_task\_channel\_read](#read)
     19 
     20 ---
     21 
     22 # kore\_task\_create {#create}
     23 ### Synopsis
     24 ```
     25 void kore_task_create(struct kore_task *t, int (*entry)(struct kore_task *))
     26 ```
     27 ### Description
     28 Creates a new task which when run will call the given callback.
     29 
     30 | Parameter | Description |
     31 | -- | -- |
     32 | t | A task data structure. |
     33 | entry | The entry point of the task when run. |
     34 
     35 ### Returns
     36 Nothing
     37 
     38 ---
     39 # kore\_task\_run {#run}
     40 ### Synopsis
     41 ```
     42 void kore_task_run(struct kore_task *t)
     43 ```
     44 ### Description
     45 Allows a task to be run. After this function returns the task will be scheduled to run.
     46 
     47 | Parameter | Description |
     48 | -- | -- |
     49 | t | A task data structure. |
     50 
     51 ### Returns
     52 Nothing
     53 
     54 ---
     55 # kore\_task\_bind\_request {#bindrequest}
     56 ### Synopsis
     57 ```
     58 void kore_task_bind_request(struct kore_task *t, struct http_request *req)
     59 ```
     60 ### Description
     61 Bind an HTTP request to a task. Binding means that the HTTP request will be scheduled to be called again by Kore if the task writes data on the task channel or when it completes.
     62 
     63 Using this in combination with the HTTP state machine allows you to build request handlers that use background tasks for heavy labor.
     64 
     65 | Parameter | Description |
     66 | -- | -- |
     67 | t | A task data structure. |
     68 | req | The HTTP request to be bound to the task. |
     69 
     70 ### Returns
     71 Nothing
     72 
     73 ---
     74 # kore\_task\_bind\_callback {#bindcallback}
     75 ### Synopsis
     76 ```
     77 void kore_task_bind_callback(struct kore_task *t, void (*cb)(struct kore_task *))
     78 ```
     79 ### Description
     80 Bind a callback to a task. Binding means that the callback will be called whenever the task writes data on the task channel or whenever it completes.
     81 
     82 | Parameter | Description |
     83 | -- | -- |
     84 | t | A task data structure. |
     85 | cb | The callback to call. |
     86 
     87 ### Returns
     88 Nothing
     89 
     90 ---
     91 # kore\_task\_destroy {#destroy}
     92 ### Synopsis
     93 ```
     94 void kore_task_destroy(struct kore_task *t)
     95 ```
     96 ### Description
     97 Destroys a task.
     98 
     99 | Parameter | Description |
    100 | -- | -- |
    101 | t | A task data structure. |
    102 
    103 ### Returns
    104 Nothing
    105 
    106 ---
    107 # kore\_task\_finished {#finished}
    108 ### Synopsis
    109 ```
    110 int kore_task_finished(struct kore_task *t)
    111 ```
    112 ### Description
    113 Check if a task has finished running.
    114 
    115 | Parameter | Description |
    116 | -- | -- |
    117 | t | A task data structure. |
    118 
    119 ### Returns
    120 Returns 1 if the task has finished running, otherwise 0.
    121 
    122 ---
    123 # kore\_task\_channel\_write {#write}
    124 ### Synopsis
    125 ```
    126 void kore_task_channel_write(struct kore_task *t, void *data, u_int32_t length)
    127 ```
    128 ### Description
    129 Write data on the task channel for the other end to read. This works both from the main thread and a task itself.
    130 
    131 | Parameter | Description |
    132 | -- | -- |
    133 | t | A task data structure. |
    134 | data | The data to be written on the channel. |
    135 | length | The length of the data to be written. |
    136 
    137 ### Returns
    138 Nothing
    139 
    140 ---
    141 
    142 # kore\_task\_channel\_read {#read}
    143 ### Synopsis
    144 ```
    145 u_int32_t kore_task_channel_read(struct kore_task *t, void *out, u_int32_t length)
    146 ```
    147 ### Description
    148 Read data from the task channel.
    149 
    150 NOTE: This is a blocking operation.
    151 
    152 | Parameter | Description |
    153 | -- | -- |
    154 | t | A task data structure. |
    155 | out | Where the data read will be written too. |
    156 | length | The maximum number of bytes that *out* can hold. |
    157 
    158 ### Returns
    159 Returns the number of original bytes from the message, if this is larger than
    160 the *length* parameter then truncation has occurred.
    161 
    162 ---