



watcher 0.2.0 documentation

 [watcher](#) 

 stable

 

First steps

* [Prerequisites](index.html#document-prerreq)

* [Quick Instalation](index.html#document-setup)

* [Quick Start](index.html#document-quickstart)

Features

* [File Watcher Features](index.html#document-features)

[watcher](#)

* »

* watcher 0.2.0 documentation

* [Edit on GitHub](https://github.com/racherb/watcher/blob/e6c5e8f107da332b36bfbad2ed9b1704e7bda8d5/docs/source/index)

---

Watcher for Watch everything![](#watcher-for-watch-everything "Permalink to this headline")

============================================================================================

[Watcher](https://watcher.readthedocs.io/en/latest/) simplifies the integration of non-connected systems

by detecting changes in data and facilitates the development of monitoring,

security and process automation applications.

Think of Watcher as an intercom or a bridge between different servers or between different

applications on the same server. Or you can simply take advantage of Watcher’s capabilities

to develop your project.

“Watch everything”Currently the functionality of detecting changes in the file system is implemented.

However, the project has a larger scope and we invite you to collaborate with us

to achieve the goal of “Watch Everything”.

One step at a time! Come on and join us.

Starting with the file system 🗂️Yes, we have started implementing watcher to observe and detect changes in the file system.

You can use watcher to discover changes related to file creation, file deletion and

file alteration. You can find out more about our all the [File Watcher Features](index.html#document-features) in these pages.

Watcher is Free, Open Source and User Focused 💓Our code is free and [open source](https://github.com/racherb/watcher).

We like open source but we like socially responsible software even more.

Watcher is distributed under MIT license.

First steps[](#first-steps "Permalink to this headline")

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

Your project needs to process inputs that trigger your business logic

but those inputs are out of your control?

Do you want to integrate your project based on detection of file system changes?

Learn about the great options Watcher offers for advanced change

detection that you can leverage for your project development.

* **Getting started**:

[Installation Prerequisites](index.html#document-prerreq) |

[Quick Installation](index.html#document-setup) |

[Feature Overview](index.html#document-features)

File Watcher features[](#file-watcher-features "Permalink to this headline")

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

Currently **Watcher** comprises the following features:

[Single File & Folders](index.html#single-file-folders),

[Multiples File Groups](index.html#multiples-file-groups),

[File Patterns](index.html#file-patterns),

[Non-Bloking Execution](index.html#non-bloking-execution),

[Blocking Execution](index.html#bloking-execution),

[Bulk File Processing](index.html#bulk-file-processing),

[Advanced File Deletion](index.html#advanced-file-deletion),

[Advanced File Creation](index.html#advanced-file-creation),

[Advanced File Alteration](index.html#advanced-file-alteration),

[Watcher for Any Alteration](index.html#watcher-for-any-alteration),

[Watcher for Specific Alteration](index.html#watcher-for-specific-alteration),

[Decoupled Execution](index.html#decoupled-execution),

[Novelty Detection](index.html#novelty-detection),

[Qualitative Response](index.html#qualitative-response),

[Check File Stability](index.html#check-file-stability),

[Big Amounts of Files](index.html#big-amounts-of-files),

[Atomic Function Injection](index.html#atomic-function-injection),

[Folder Recursion](index.html#folder-recursion),

[Selective Path Level](index.html#selective-path-level),

[Watcher Monitoring](index.html#watcher-monitoring)

### Prerequisites[](#prerequisites "Permalink to this headline")

If you like containers we have one ready in **DocketHub** ([watcher](https://hub.docker.com/r/racherb/watcher))

but if you want to install **Watcher** you should consider the following requirements:

#### Tarantool[](#tarantool "Permalink to this headline")

**Watcher runs on Tarantool**. Tarantool is an In-memory computing platform.

For installation follow the instructions on the

[tarantool.io](https://www.tarantool.io/en/download/os-installation/) website.

Before you begin, ensure you have met the following requirements:

* **Tarantool**: `>= 1.7`.

Note

If you already have Tarantool installed you can skip this step.

#### Supported Platforms[](#supported-platforms "Permalink to this headline")

* **POSIX Compliant**: `Unix`, `MacOsx`, `Linux`, `Freebsd`.

* **POSIX for Windows**: `Cygwin`, `Microsoft POSIX Subsystem`, `Windows Services for UNIX`, `MKS Toolkit`.

Warning

Watcher has not been tested on POSIX Windows Systems.

### Quick Instalation[](#quick-instalation "Permalink to this headline")

There are several ways to install **Watcher** on your server.

Choose the option that suits you best and go ahead!

#### From Docker[](#from-docker "Permalink to this headline")

Get **Watcher** container from a docker image:

```

1docker pull racherb/watcher:latest

2docker run -i -t racherb/watcher

```

Note

**Use docker volumes**. If you want to look at the host or remote machine’s file system

then start a container with a `volume`.

The following example enables a volume on the temporary folder `/tmp` of the host

at path `/opt/watcher/host/` of the container.

`docker run -i -t -v /tmp/:/opt/watcher/host/tmp racherb/watcher`

#### From DEB Package[](#from-deb-package "Permalink to this headline")

Quick installation from DEB Package:

```

1curl -s https://packagecloud.io/install/repositories/iamio/watcher/script.deb.sh | sudo bash

2sudo apt-get install watcher

```

Note

*DEB Quick install* is available for the following distributions:

* **Debian**: `Lenny`, `Trixie`, `Bookworm`, `Bullseye`, `Buster`, `Stretch`, `Jessie`.

* **Ubuntu**: `Cosmic`, `Disco`, `Hirsute`, `Groovy`, `Focal`.

* **ElementaryOS**: `Freya`, `Loki`, `Juno`, `Hera`.

#### From RPM Package[](#from-rpm-package "Permalink to this headline")

First install the repository:

```

curl -s https://packagecloud.io/install/repositories/iamio/watcher/script.rpm.sh | sudo bash

```

And install the package:

* For **RHEL** and **Fedora** distros: `sudo yum install watcher-0.2.1-1.noarch`.

* For **Opensuse** and **Suse Linux Enterprise**: `sudo zypper install watcher-0.2.1-1.noarch`.

Note

*RPM Quick install* is available for the following distributions:

* **RHEL**: `7`, `6`, `8`.

* **Fedora**: `29`, `30`, `31`, `32`, `33`.

* **OpenSuse**: `15.1`, `15.2`, `15.3`, `42.1`, `42.2`, `42.3`.

* **Suse Linux Enterprise**: `12.4`, `12.5`, `15.0`, `15.1`, `15.2`, `15.3`.

#### From Tarantool[](#from-tarantool "Permalink to this headline")

Quick installation from **Utility Tarantool**:

Install watcher through Tarantool’s `tarantoolctl` command:

```

1tarantoolctl rocks install avro-schema

2tarantoolctl rocks install https://raw.githubusercontent.com/racherb/watcher/master/watcher-scm-1.rockspec

```

#### From LuaRocks[](#from-luarocks "Permalink to this headline")

Make sure you have Luarocks installed first.

From the `terminal` run the following command:

```

luarocks install https://raw.githubusercontent.com/racherb/watcher/master/watcher-scm-1.rockspec

```

### Quick Start[](#quick-start "Permalink to this headline")

Detection of `creation`, `deletion` and `alteration` of **single files** or **single folders** in the file system.

```

1fwa = require('watcher').file               --for file-watcher

2fwa.creation({'/path/to/single\_file'})      --watching file creation

3fwa.deletion({'/path/to/single\_folder/'})   --watching folder deletion

4fwa.alteration('/path/to/single\_folder/\*')  --watching file alteration

```

### File Watcher Features[](#file-watcher-features "Permalink to this headline")

The **Watcher** module has been designed with the typical use cases of the Banking

and Telecommunications industry in mind for *IT Batch Processing*.

If you know of a use case that is not covered by watcher,

please tell us about it in the

[GitHub Discussions Section](https://github.com/racherb/watcher/discussions/categories/ideas/) .

Currently **Watcher** comprises the following features:

[Single File & Folders](#single-file-folders),

[Multiples File Groups](#multiples-file-groups),

[File Patterns](#file-patterns),

[Non-Bloking Execution](#non-bloking-execution),

[Blocking Execution](#bloking-execution),

[Bulk File Processing](#bulk-file-processing),

[Advanced File Deletion](#advanced-file-deletion),

[Advanced File Creation](#advanced-file-creation),

[Advanced File Alteration](#advanced-file-alteration),

[Watcher for Any Alteration](#watcher-for-any-alteration),

[Watcher for Specific Alteration](#watcher-for-specific-alteration),

[Decoupled Execution](#decoupled-execution),

[Novelty Detection](#novelty-detection),

[Qualitative Response](#qualitative-response),

[Check File Stability](#check-file-stability),

[Big Amounts of Files](#big-amounts-of-files),

[Atomic Function Injection](#atomic-function-injection),

[Folder Recursion](#folder-recursion),

[Selective Path Level](#selective-path-level),

[Watcher Monitoring](#watcher-monitoring)

Note

The lines of code used to exemplify each feature of watcher assume the following:

```

1fwa = require('watcher').file   --for file-watcher

2mon = require('watcher').monit  --for watcher monitoring

```

#### Single File & Folders[](#single-file-folders "Permalink to this headline")

Detection of `creation`, `deletion` and `alteration` of **single files** or **single folders** in the file system.

```

1fwa.creation({'/path/to/single\_file'})    --watching file creation

2fwa.creation({'/path/to/single\_folder/'}) --watching folder creation

```

#### Multiples File Groups[](#multiples-file-groups "Permalink to this headline")

Multiple groups of different files can be watched at the same time.

The input list of watchable files is a Lua table type parameter.

```

1fwa.deletion(

2    {

3 '/path\_1/to/group\_file\_a/\*', --folder

4 '/path\_2/to/group\_file\_b/\*' --another

5     }

6 )

```

#### File Patterns[](#file-patterns "Permalink to this headline")

```

fwa.creation({'/path/to/files\_\*.txt'})

```

Note

The *watch-list* is constructed with a single flag that controls the behavior of the function: **GLOB\_NOESCAPE**.

For details type `man 3 glob`.

#### Non-Bloking Execution[](#non-bloking-execution "Permalink to this headline")

By default the **Watcher** run is executed in non-blocking mode through tarantool fibers.

Fibers are a unique Tarantool feature *“green threads”* or coroutines that run independently

of operating system threads.

#### Blocking Execution[](#blocking-execution "Permalink to this headline")

The `waitfor` function blocks the code and waits for a watcher to finish.

```

waitfor(fwa.creation({'/path/to/file'}).wid) --wait for watcher

```

#### Bulk File Processing[](#bulk-file-processing "Permalink to this headline")

**Watcher** has an internal mechanism to allocate fibers for every certain amount of files

in the watcher list. This amount is determined by the `BULK\_CAPACITY` configuration value

in order to optimize performance.

#### Advanced File Deletion[](#advanced-file-deletion "Permalink to this headline")

##### Inputs[](#inputs "Permalink to this headline")

File Watcher Deletion Parameters[](#id31 "Permalink to this table")

| Param | Type | Description |

| --- | --- | --- |

| wlist | `table`, `required` | Watch List |

| maxwait | `number`, `otional`, `default-value: 60` | Maximum wait time in seconds |

| interval | `number`, `otional`, `default-value: 0.5` | Verification interval for watcher in seconds |

| options | `table`, `optional`, `default-value: {'NS', 0, 0}` | List of search options |

| recursion | `table`, `optional`, `default-value: nil` or `{false, {0}, false}` | Recursion paramaters |

##### wlist[](#wlist "Permalink to this headline")

It is the list of files, directories or file patterns to be observed. The data type is a Lua table and

the size of tables is already limited to `2.147.483.647` elements.

An example definition is the following:

```

wlist = {'path/file', 'path', 'pattern\*', ...} --arbitrary code

```

##### maxwait[](#maxwait "Permalink to this headline")

Maxwait is a numeric value that represents the maximum time to wait for the watcher.

Watcher will terminate as soon as possible and as long as the search conditions are met.

The default value is `60 seconds`.

##### interval[](#interval "Permalink to this headline")

Interval is a numerical value that determines how often the watcher checks the search conditions.

This value must be less than the maxwait value.

The default value is `0.5` seconds.

##### options[](#options "Permalink to this headline")

The options parameter is a Lua table containing 3 elements: `sort`, `cases` and `match`.

* The first one `sort` contains the ordering method of the `wlist`.

* The second element `cases` contains the number of cases to observe from the wlist.

* and the third element `match` indicates the number of cases expected to satisfy the search.

By default, the value of the option table is `{sort = 'NS', cases = 0, match = 0}`.

The list of possible values for `sort`[](#id32 "Permalink to this table")

| Value | Description |

| --- | --- |

| `'NS'` | No sort |

| `'AA'` | Sorted alphabetically ascending |

| `'AD'` | Sorted alphabetically descending |

| `'MA'` | Sorted by date of modification ascending |

| `'MD'` | Sorted for date of modification descending |

Note

The value `'NS'` treats the list in the same order in which the elements

are passed to the list `wlist`.

##### recursion[](#recursion "Permalink to this headline")

To enable directory recursion you must define the recursion parameter.

The recursion works only for an observable of type directory.

The recursion value is a Lua table type composed of the following elements `{recursive\_mode, {deep\_levels}, hidden\_files}`:

* **recursive\_mode**: Boolean indicating whether or not to activate the recursive mode on the root directory. The default value is `false`.

* **deep\_levels**: Numerical table indicating the levels of depth to be evaluated in the directory structure. The default value is `{0}`

* **hidden\_files**: Boolean indicating whether hidden files will be evaluated in the recursion. The default value is `false`.

##### How do the recursion levels work?[](#how-do-the-recursion-levels-work "Permalink to this headline")

To understand how levels work in recursion, let’s look at the following example.

Imagine you have the following directory structure and you want to observe

the deletion of files from the path **‘/folder\_A/folder\_B/’**.

[![Recursive levels](_images/recursive-levels.png)](_images/recursive-levels.png)

The levels are determined from the object path or root path that will be used as input

in the watcher expression. In this case the path **‘/folder\_A/folder\_B/’** has level zero and,

for each folder node a level will be added according to its depth.

The result is shown in the following summary table, which contains the list of files

for each level.

Identification of the levels of recursion[](#id33 "Permalink to this table")

|  | [Input] Level 0 `{0}` | Level 1 `{1}` | Level 2 `{2}` | Level 3 `{3}` | Level 4 `{4}` |

| --- | --- | --- | --- | --- | --- |

| **folder** | `'/folder\_A/folder\_B/'` | `'folder\_C'` | `'folder\_D'` | `'folder\_E'` | `'folder\_N'` |

| **files** | `{A1}` `{B1, B2, .B3}` | `{C1, C2}` | `{.D1}` | `{E1, E2, .E3}` | `{N1, N2}` |

Note

The files, `.B3`, `.D1` and `.E3` are hidden files.

Now that we know how to set the recursion level, let’s see an example of the

observable files depending on different values of the **recursion** parameter

for the above mentioned example.

Observable files depending on the recursion level[](#id34 "Permalink to this table")

| `recursion` value | Composition of the list of observable files `wlist` |

| --- | --- |

| `{true, {0}, false}` | `{A1, B1, B2}` |

| `{true, {0}, true}` | `{A1, B1, B2, .B3}` |

| `{true, {0, 1}, false}` | `{A1, B1, B2, C1, C2}` |

| `{true, {0, 1}, true}` | `{A1, B1, B2, .B3, C1, C2}` |

| `{true, {2}, false}` | `nil` |

| `{true, {2}, true}` | `{.D1}` |

| `{true, {0, 1, 2, 3, 4}, false}` | `{A1, B1, B2, C1, C2, E1, E2, N1, N2}` |

| `{true, {0, 1, 2, 3, 4}, true}` | `{A1, B1, B2, .B3, C1, C2, .D1, E1, E2, .E3, N1, N2}` |

##### Output[](#output "Permalink to this headline")

#### Advanced File Creation[](#advanced-file-creation "Permalink to this headline")

##### Inputs[](#id9 "Permalink to this headline")

File Watcher Creation Parameters[](#id35 "Permalink to this table")

| Param | Type | Description |

| --- | --- | --- |

| wlist | `table`, `required` | Watch List |

| maxwait | `number`, `otional`, `default-value: 60` | Maximum wait time in seconds |

| interval | `number`, `otional`, `default-value: 0.5` | Verification interval for watcher in seconds |

| minsize | `number`, `optional`, `default-value: 0` | Value of the minimum expected file size |

| stability | `table`, `optional`, `default-value: {1, 15}` | Minimum criteria for measuring file stability |

| novelty | `table`, `optional`, `default-value: {0, 0}` | Time interval that determines the validity of the file’s novelty |

| nmatch | `number`, `optional`, `default-value: 0` | Number of expected files as a search sufficiency condition |

##### wlist[](#id10 "Permalink to this headline")

It is the list of files, directories or file patterns to be observed. The data type is a Lua table and

the size of tables is already limited to `2.147.483.647` elements.

An example definition is the following:

```

wlist = {'path/file', 'path', 'pattern\*', ...} --arbitrary code

```

##### maxwait[](#id11 "Permalink to this headline")

Maxwait is a numeric value that represents the maximum time to wait for the watcher.

Watcher will terminate as soon as possible and as long as the search conditions are met.

The default value is `60 seconds`.

##### interval[](#id12 "Permalink to this headline")

Interval is a numerical value that determines how often the watcher checks the search conditions.

This value must be less than the maxwait value.

The default value is `0.5` seconds.

##### minsize[](#minsize "Permalink to this headline")

Minsize is a numerical value representing the minimum expected file size.

The default value is `0`, which means that it is sufficient to just generate the file when the minimum size is unknown.

Important

Regardless of whether the expected file size is `0 Bytes`,

watcher will not terminate until the file arrives in its entirety,

avoiding edge cases where a file is consumed before the data transfer is complete.

##### stability[](#stability "Permalink to this headline")

The `stability` parameter contains the elements that allow to evaluate the stability of a file.

It is a Lua table containing two elements:

* The `interval` that defines the frequency of checking the file once it has arrived.

* The number of `iterations` used to determine the stability of the file.

The default value is: `{1, 15}`.

##### novelty[](#novelty "Permalink to this headline")

The `novelty` parameter is a two-element Lua table that contains the

time interval that determines the validity of the file’s novelty.

The default value is `{0, 0}` which indicates that the novelty of the file will not be evaluated.

##### nmatch[](#nmatch "Permalink to this headline")

`nmatch` is a number of expected files as a search sufficiency condition.

#### Advanced File Alteration[](#advanced-file-alteration "Permalink to this headline")

##### Inputs[](#id15 "Permalink to this headline")

File Watcher Alteration Parameters[](#id36 "Permalink to this table")

| Param | Type | Description |

| --- | --- | --- |

| wlist | `table`, `required` | Watch List |

| maxwait | `numeric`, `otional`, `default-value: 60` | Maximum wait time in seconds |

| interval | `numeric`, `otional`, `default-value: 0.5` | Verification interval for watcher in seconds |

| awhat | `string`, `optional`, `default-value: '1'` | Type of file alteration to be observed |

| nmatch | `number`, `optional`, `default-value: 0` | Number of expected files as a search sufficiency condition |

##### wlist[](#id16 "Permalink to this headline")

It is the list of files, directories or file patterns to be observed. The data type is a Lua table and

the size of tables is already limited to `2.147.483.647` elements.

An example definition is the following:

```

wlist = {'path/file', 'path', 'pattern\*', ...} --arbitrary code

```

##### maxwait[](#id17 "Permalink to this headline")

Maxwait is a numeric value that represents the maximum time to wait for the watcher.

Watcher will terminate as soon as possible and as long as the search conditions are met.

The default value is `60 seconds`.

##### interval[](#id18 "Permalink to this headline")

Interval is a numerical value that determines how often the watcher checks the search conditions.

This value must be less than the maxwait value.

The default value is `0.5` seconds.

##### awhat[](#awhat "Permalink to this headline")

Type of file alteration to be observed. See [File Watcher Alteration Parameters](#file-watcher-alteration-parameters).

File Watcher Alteration Parameters[](#id37 "Permalink to this table")

| Type | Value | Description |

| --- | --- | --- |

| `ANY\_ALTERATION` | `'1'` | Search for any alteration |

| `CONTENT\_ALTERATION` | `'2'` | Search for content file alteration |

| `SIZE\_ALTERATION` | `'3'` | Search for file size alteration |

| `CHANGE\_TIME\_ALTERATION` | `'4'` | Search for file `ctime` alteration |

| `MODIFICATION\_TIME\_ALTERATION` | `'5'` | Search for file `mtime` alteration |

| `INODE\_ALTERATION` | `'6'` | Search for file `inode` alteration |

| `OWNER\_ALTERATION` | `'7'` | Search for file `owner` alteration |

| `GROUP\_ALTERATION` | `'8'` | Search for file `group` alteration |

##### nmatch[](#id19 "Permalink to this headline")

`nmatch` is a number of expected files as a search sufficiency condition.

#### Watcher for Any Alteration[](#watcher-for-any-alteration "Permalink to this headline")

```

fwa.alteration({'/path/to/file'}, nil, nil, '1')

```

#### Watcher for Specific Alteration[](#watcher-for-specific-alteration "Permalink to this headline")

```

1fwa.alteration({'/path/to/file'}, nil, nil, '2') --Watcher for content file alteration

2fwa.alteration({'/path/to/file'}, nil, nil, '3') --Watcher for content file size alteration

3fwa.alteration({'/path/to/file'}, nil, nil, '4') --Watcher for content file ctime alteration

4--explore other options for 'awhat' values

```

See table [File Watcher Alteration Parameters](#file-watcher-alteration-parameters) for more options.

#### Decoupled Execution[](#decoupled-execution "Permalink to this headline")

The `create`, `run` function and the `monit` options have been decoupled

for better behavior, overhead relief and versatility of use.

#### Novelty Detection[](#novelty-detection "Permalink to this headline")

**Watcher** implements the detection of the newness of a file based on the `mtime` modification date.

This is useful to know if file system items have been created in an expected time window.

Warning

Note that the creation of the files may have been done preserving the attributes of the original file.

In that case you should consider the novelty rank accordingly.

```

1 date\_from  = os.time() - 24\*60\*60 --One day before the current date

2 date\_to    = os.time() + 24\*60\*60 --One day after the current date

3 os.execute('touch /tmp/novelty\_file.txt') --The file is created on the current date

4 fwt.creation({'/tmp/novelty\_file.txt'}, 10, nil, 0, nil, {date\_from, date\_to})

```

Note

> 

> For known dates you can use the Lua function **os.time()** as follows:

> 

> 

> 

```

 1  date\_from = os.time(

 2      {

 3          year = 2020,

 4          month = 6,

 5          day = 4,

 6          hour = 23,

 7          min = 48,

 8          sec = 10

 9      }

10  )

```

#### Qualitative Response[](#qualitative-response "Permalink to this headline")

Watcher leaves a record for each watchable file where it provides qualitative

nformation about the search result for each of them.

To explore this information see the [Watcher Monitoring](#watcher-monitoring) `match` and `nomatch` functions.

```

 1 NOT\_YET\_CREATED = '\_'               --The file has not yet been created

 2 FILE\_PATTERN = 'P'                  --This is a file pattern

 3 HAS\_BEEN\_CREATED = 'C'              --The file has been created

 4 IS\_NOT\_NOVELTY = 'N'                --The file is not an expected novelty

 5 UNSTABLE\_SIZE = 'U'                 --The file has an unstable file size

 6 UNEXPECTED\_SIZE = 'S'               --The file size is unexpected

 7 DISAPPEARED\_UNEXPECTEDLY = 'D'      --The file has disappeared unexpectedly

 8 DELETED = 'X'                       --The file has been deleted

 9 NOT\_EXISTS = 'T'                    --The file does not exist

10 NOT\_YET\_DELETED = 'E'               --The file has not been deleted yet

11 NO\_ALTERATION = '0'                 --The file has not been modified

12 ANY\_ALTERATION = '1'                --The file has been modified

13 CONTENT\_ALTERATION = '2'            --The content of the file has been altered

14 SIZE\_ALTERATION = '3'               --The file size has been altered

15 CHANGE\_TIME\_ALTERATION = '4'        --The ctime of the file has been altered

16 MODIFICATION\_TIME\_ALTERATION = '5'  --The mtime of the file has been altered

17 INODE\_ALTERATION = '6'              --The number of inodes has been altered

18 OWNER\_ALTERATION = '7'              --The owner of the file has changed

19 GROUP\_ALTERATION = '8'              --The group of the file has changed

```

#### Check File Stability[](#check-file-stability "Permalink to this headline")

Enabled only for file creation.

This feature ensures that the **watcher** terminates once the file creation is completely finished.

This criterion is independent of the file size.

See usage for parameter [stability](#stability)

#### Big Amounts of Files[](#big-amounts-of-files "Permalink to this headline")

In the following example, watching the file deletion from the path “/” recursively

down to depth level 3 (`levels={0,1,2,3}`) yields a total of **163,170 watchable files**.

Note that the execution takes 85 seconds (on a typical desktop machine) but the maximum timeout

of the watcher has been specified as low as 10 seconds.

This means that 88% of the time is consumed in creating the watcher due to recursion.

> 

> 

> ```

>  1  tarantool> test=function() local ini=os.time() local fwa=fw.deletion({'/'}, 10, nil, {'NS', nil, 2}, {true, {0,1,2,3}, false}) print(os.time()-ini) print(fwa.wid) end

>  2  tarantool> test()

>  3  85

>  4  1620701962375155ULL

>  5  ---

>  6  tarantool> mon.info(1620701962375155ULL)

>  7  ---

>  8  - ans: true

>  9 match: 72

> 10  what: '{"/"}'

> 11  wid: 1620701962375155

> 12  type: FWD

> 13 nomatch: 163098

> 14  status: completed

> 15  ...

> 

> ```

> 

> 

> 

#### Atomic Function Injection[](#atomic-function-injection "Permalink to this headline")

Atomic function injection allows you

to perform specific tasks on each element of the watchable list separately.

In the example, the atomic function afu creates a backup copy for each element of the watchlist.

```

1afu = function(file) os.execute('cp '..file..' '..file..'\_backup') end --Atomic Funcion

2cor = require('watcher').core

3wat = cor.create({'/tmp/original.txt'}, 'FWD', afu) --afu is passed as parameter

4res = run\_watcher(wat)

```

#### Folder Recursion[](#folder-recursion "Permalink to this headline")

You can enable recursion on directories to detect changes in the file system.

Recursion is enabled based on a directory entry as a parameter that is considered as a

root directory. Starting from this root directory, considered as level zero,

you can selectively activate the observation of successive directory levels.

```

 1 fwa.deletion(

 2     {'/tmp/folder\_1'}, --Observed directory is considered a zero level root directory

 3     nil,               --Maxwait, nil to take the value by omission

 4     nil,               --Interval, nil to take the value by omission

 5     nil,               --Options, nil to take the value by omission

 6 {

 7 true, --Activate recursion

 8 {0, 1, 2}, --Levels of directories to be observed (root and levels 1 & 2)

 9 false --Includes hidden files

10 }

11 )

```

For more info see [How do the recursion levels work?](#how-do-the-recursion-levels-work).

#### Selective Path Level[](#selective-path-level "Permalink to this headline")

The recursion levels is a list of numerical values so you can specify (selectively)

the directory level you want to observe and ignore others. This is useful in situations where the full path

to the file is unknown but the depth or level of the file is known.

```

 1 fwa.deletion(

 2     {'/bac/invoices'},

 3     nil,

 4     nil,

 5     nil,

 6     {

 7         true,          --Activate recursion

 8 {3}, --Selective level 3

 9         false          --Includes hidden files

10     }

11 )

```

See use case …

#### Watcher Monitoring[](#watcher-monitoring "Permalink to this headline")

`monit` for Watcher monitoring allows you to monitor and explore the running status of a watcher.

##### info[](#info "Permalink to this headline")

The output is a Lua table containing the following elements:

* **ans** is a boolean value containing the response of the watcher. `true` means that the watcher has detected the expected changes that are defined in the parameters.

* **match** is the number of cases that match the `true` value of **ans**.

* **nomatch** is the number of cases that do not belong to the set of `true` **ans**.

* **what** is a string containing the obserbables parameter.

* **wid** is the unique identifier of the watcher.

* **type** is the type of the watcher

* **status** is the execution status of the watcher.

```

 1   mon.info(1620701962375155ULL)

 2

 3     {

 4         ans: true

 5         match: 72

 6         what: '{"/"}'

 7         wid: 1620701962375155

 8         type: 'FWD'

 9         nomatch: 163098

10         status: 'completed'

11     }

```

##### match[](#match "Permalink to this headline")

##### nomatch[](#nomatch "Permalink to this headline")

