expirationd

https://tarantool.github.io/expirationd/
Admin
expirationd is a Tarantool module for running scheduled background tasks to check, expire, and...
Tokens:4,592
Snippets:56
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### expirationd.start usage example

Source: https://tarantool.github.io/expirationd/index.html

Shows how to start an expirationd task. It requires the expirationd module, configures box, defines an is_expired function that always returns true, and a delete_tuple function to remove tuples. The start call uses process_expired_tuple, tuples_per_iteration, and full_scan_time options.

```lua
local expirationd = require('expirationd')

box.cfg{}

local space = box.space.old
local job_name = "clean_all"

local function is_expired(args, tuple)
    return true
end

local function delete_tuple(space, args, tuple)
    box.space[space]:delete{tuple[1]}
end

expirationd.start(job_name, space.id, is_expired, {
    process_expired_tuple = delete_tuple,
    args = nil,
    tuples_per_iteration = 50,
    full_scan_time = 3600
})
```

--------------------------------

### start(name, space_id, is_expired, {options})

Source: https://tarantool.github.io/expirationd/index.html

Starts a new expiration task. The task periodically scans the space and processes expired tuples.

```APIDOC
## start(name, space_id, is_expired, {options})

### Description
Starts a new expiration task. The task periodically scans the space and processes expired tuples.

### Method
start

### Parameters
#### name (string) - Required - Task name.
#### space_id (number) - Required - Space identifier.
#### is_expired (func) - Required - Function to check if a tuple is expired.
#### options (table) - Optional - Options table with the following fields:
- **args** (any) - Optional - Arguments passed to the is_expired and process_expired_tuple functions.
- **full_scan_time** (number) - Optional - Time in seconds for a full scan. Default is 3600.
- **iteration_delay** (number) - Optional - Max sleep time between iterations (in seconds). Default is 1 sec.
- **iterator_type** (string) - Optional - Type of iterator to use, as string or box.index constant, default is box.index.ALL.
- **on_full_scan_complete** (func) - Optional - Function to call after completing a full scan iteration.
- **on_full_scan_error** (func) - Optional - Function to call after terminating a full scan due to an error.
- **on_full_scan_start** (func) - Optional - Function to call before starting a full scan iteration.
- **on_full_scan_success** (func) - Optional - Function to call after successfully completing a full scan iteration.
- **process_expired_tuple** (func) - Optional - Applied to expired tuples, receives space, args, tuple as arguments. When not passed, tuples are removed.
- **process_while** (func) - Optional - Function to call before checking each tuple. If it returns false, the task will stop until next full scan.
- **start_key** (any) - Optional - Start iterating from the tuple with this index value.
- **tuples_per_iteration** (number) - Optional - Number of tuples to check in one batch. Default is 1024.
- **vinyl_assumed_space_len_factor** (number) - Optional - Factor for recalculation of vinyl space size. Default is 2.
- **vinyl_assumed_space_len** (number) - Optional - Assumed size of vinyl space in the first iteration. Default is 10^7.

### Returns
task instance

### Usage
```
local expirationd = require('expirationd')

box.cfg{}

local space = box.space.old
local job_name = "clean_all"

local function is_expired(args, tuple)
    return true
end

local function delete_tuple(space, args, tuple)
    box.space[space]:delete{tuple[1]}
end

expirationd.start(job_name, space.id, is_expired, {
    process_expired_tuple = delete_tuple,
    args = nil,
    tuples_per_iteration = 50,
    full_scan_time = 3600
})
```
```

--------------------------------

### Example process_while callback function

Source: https://tarantool.github.io/expirationd/index.html

Example callback for the process_while option. It always returns false, which stops the task until the next full scan.

```lua
 local function process_while()
     return false
 end
```

--------------------------------

### Example on_full_scan_error callback function

Source: https://tarantool.github.io/expirationd/index.html

Example callback for the on_full_scan_error option. It calls pcall(fiber.sleep, 1) to pause the fiber for 1 second after an error.

```lua
 local function on_full_scan_error()
     pcall(fiber.sleep, 1)
 end
```

--------------------------------

### start(name, space, is_tuple_expired[, options])

Source: https://tarantool.github.io/expirationd/index.html

Run a scheduled task to check and process (expire) tuples in a given space.

```APIDOC
## start(name, space, is_tuple_expired[, options])

### Description
Run a scheduled task to check and process (expire) tuples in a given space.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
- **name** (string) - Required - Task name.
- **space** (string) - Required - Space to look in for expired tuples. Can be numeric or string (space id or name).
- **is_tuple_expired** (func) - Required - Function that accepts tuple and returns true/false (is tuple expired or not).

#### Request Body
- **options** (table, optional) - Table with named options.
  - **args** (any, optional) - Passed to `is_tuple_expired()` and `process_expired_tuple()` as additional context.
  - **atomic_iteration** (boolean, optional) - False (default) to process each tuple as a single transaction, true to process tuples from each batch in a single transaction.
  - **force** (boolean, optional) - Force enable task processing on read-only instances for non-local persistent spaces.
  - **force_allow_functional_index** (boolean, optional) - Skip error on iteration through a functional index for Tarantool < 2.8.4.
  - **full_scan_delay** (number, optional) - Sleep time between full scans (in seconds). Default 1 sec.
  - **full_scan_time** (number, optional) - Time required for a full index scan (in seconds). Default 3600.
  - **index** (string, optional) - Name or id of the index to iterate on. Default primary index.
  - **iterate_with** (func, optional) - Function which returns an iterator object to check tuples.
  - **iteration_delay** (number, optional) - Sleep time between iterations.

### Returns
None

```

--------------------------------

### start(name, space, is_tuple_expired[, options])

Source: https://tarantool.github.io/expirationd/index.html

Runs a scheduled task to check and process (expire) tuples in a given space.

```APIDOC
## start(name, space, is_tuple_expired[, options])

### Description
Run a scheduled task to check and process (expire) tuples in a given space.

### Parameters
- **name** - Task name.
- **space** - Space to process.
- **is_tuple_expired** - Function to determine if a tuple is expired.
- **options** (optional) - Additional options.

### Returns
Not specified in the source.

```

--------------------------------

### tasks() return structure example

Source: https://tarantool.github.io/expirationd/index.html

Shows the structure of the response from the tasks() function, which returns a list of task names.

```json
 {
     "expirationd-1"
     "expirationd-2",
     "expirationd-3",
 }
```

--------------------------------

### Example process_expired_tuple callback function

Source: https://tarantool.github.io/expirationd/index.html

Example callback for the process_expired_tuple option. It deletes the expired tuple from the space and optionally archives the email to another space.

```lua
 local function put_tuple_to_archive(space, args, tuple)
     box.space[space]:delete{tuple[1]}
     local email = tuple[2]
     if args.archive_space ~= nil and email ~= nil then
         box.space[args.archive_space]:replace{email, fiber.time()}
     end
 end
```

--------------------------------

### task.start(self)

Source: https://tarantool.github.io/expirationd/index.html

Starts a task. It continues processing from the last tuple if the task was previously stopped and has default start_key and iterate_with functions.

```APIDOC
## task.start(self)

### Description
Start a task. It continues processing from a last tuple if the task was previously stopped by task.stop and the task has default `start_key` and `iterate_with` functions.

### Parameters
- **self** - Task instance.

### Returns
None

```

--------------------------------

### task(name)

Source: https://tarantool.github.io/expirationd/index.html

Gets a task by name.

```APIDOC
## task(name)

### Description
Get task by name.

### Parameters
- **name** - Task name.

### Returns
Task object.

```

--------------------------------

### Get expirationd configuration value

Source: https://tarantool.github.io/expirationd/index.html

Retrieves the current value of the metrics configuration option.

```lua
print(expirationd.cfg.metrics)
 true
```

--------------------------------

### Define custom iteration function

Source: https://tarantool.github.io/expirationd/index.html

Example of a custom iterate_with function to control how tuples are retrieved for processing.

```lua
  local function iterate_with()
      index:pairs(option.start_key(), {
         iterator = option.iterator_type
      }):take_while(
             function()
                 return option.process_while()
             end
        )
  end
```

--------------------------------

### Define tuple expiration function

Source: https://tarantool.github.io/expirationd/index.html

Example of a function that determines if a tuple has expired based on a field value and current time.

```lua
local function is_tuple_expired(args, tuple)
     local tuple_expire_time = get_field(tuple, args.field_no)
     local current_time = fiber.time()
     return current_time >= tuple_expire_time
 end
```

--------------------------------

### cfg(options)

Source: https://tarantool.github.io/expirationd/index.html

Configure expirationd module options.

```APIDOC
## cfg(options)

### Description
Configure expirationd module options.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Request Body
- **options** (table) - Required - Configuration options table.
  - **metrics** (bool, optional) - Enable or disable stats collection by metrics. Default is enabled.

### Returns
None

```

--------------------------------

### tasks()

Source: https://tarantool.github.io/expirationd/index.html

Returns a list of all task names.

```APIDOC
## tasks()

### Description
Return a list with task's names.

### Method
tasks

### Returns
Response of the following structure:
```
{
    "expirationd-1"
    "expirationd-2",
    "expirationd-3",
}
```
```

--------------------------------

### tasks()

Source: https://tarantool.github.io/expirationd/index.html

Returns a list of task names.

```APIDOC
## tasks()

### Description
Return a list with task's names.

### Parameters
None.

### Returns
List of task names.

```

--------------------------------

### cfg(options)

Source: https://tarantool.github.io/expirationd/index.html

Configures expirationd with the given options.

```APIDOC
## cfg(options)

### Description
Configure expirationd.

### Parameters
- **options** - Configuration options.

### Returns
Not specified in the source.

```

--------------------------------

### task.restart(self)

Source: https://tarantool.github.io/expirationd/index.html

Restarts a task.

```APIDOC
## task.restart(self)

### Description
Restart a task.

### Parameters
- **self** - Task instance.

### Returns
None

```

--------------------------------

### Configure expirationd metrics

Source: https://tarantool.github.io/expirationd/index.html

Sets the metrics configuration option for the expirationd module.

```lua
expirationd.cfg({metrics = true})
```

--------------------------------

### stats([name])

Source: https://tarantool.github.io/expirationd/index.html

Returns task statistics in a table. If a name is provided, returns statistics for that task; otherwise returns statistics for all tasks.

```APIDOC
## stats([name])

### Description
Return task statistics in table.

### Parameters
- **name** (optional) - Task name.

### Returns
Task statistics in table.

```

--------------------------------

### update()

Source: https://tarantool.github.io/expirationd/index.html

Reloads the module.

```APIDOC
## update()

### Description
Reload module.

### Parameters
None.

### Returns
Not specified in the source.

```

--------------------------------

### task.statistics(self)

Source: https://tarantool.github.io/expirationd/index.html

Returns statistics about a task, including checked count, expired count, restarts, and working time.

```APIDOC
## task.statistics(self)

### Description
Get statistics about a task.

### Parameters
- **self** - Task instance.

### Returns
Response of the following structure:
```
{
    checked_count = number,
    expired_count = number,
    restarts = number,
    working_time = number,
}
```
where:
- `checked_count` is a number of tuples checked for expiration (expired + skipped).
- `expired_count` is a number of expired tuples.
- `restarts` is a number of restarts since start. From the start `restarts` is equal to 1.
- `working_time` is a task's operation time.

```

--------------------------------

### kill(name)

Source: https://tarantool.github.io/expirationd/index.html

Kills an existing task by name.

```APIDOC
## kill(name)

### Description
Kill an existing task.

### Parameters
- **name** - Task name.

### Returns
Not specified in the source.

```

--------------------------------

### Task statistics structure

Source: https://tarantool.github.io/expirationd/index.html

The structure of the table returned by the task.statistics method.

```lua
 {
     checked_count = number,
     expired_count = number,
     restarts = number,
     working_time = number,
 }
```

--------------------------------

### stats([name])

Source: https://tarantool.github.io/expirationd/index.html

Returns statistics for a specific task or for all tasks.

```APIDOC
## stats([name])

### Description
Return task statistics in table.

### Method
stats

### Parameters
#### name (string) - Optional - Task name. If name is nil, then return map of name:stats, else return map with stats.

### Returns
Task statistics in table.
```

--------------------------------

### kill(name)

Source: https://tarantool.github.io/expirationd/index.html

Kills an existing expiration task by name.

```APIDOC
## kill(name)

### Description
Kill an existing task.

### Method
kill

### Parameters
#### name (string) - Required - Task name.

### Returns
None
```

--------------------------------

### task.stop(self)

Source: https://tarantool.github.io/expirationd/index.html

Stops a task.

```APIDOC
## task.stop(self)

### Description
Stop a task.

### Parameters
- **self** - Task instance.

### Returns
None

```

--------------------------------

### task.kill(self)

Source: https://tarantool.github.io/expirationd/index.html

Kills a task. Stops the task and deletes it from the list of tasks.

```APIDOC
## task.kill(self)

### Description
Kill a task. Stop a task and delete it from list of tasks.

### Parameters
- **self** - Task instance.

### Returns
None

```
Tokens:
Raw