# Workers Documentation

Background workers process long-running operations asynchronously, allowing the web interface to remain responsive.

## Overview

Workers are long-running PHP CLI scripts that:

- Poll the database for queued jobs
- Process jobs of a specific type
- Handle errors gracefully
- Log progress and results
- Run continuously until stopped

## Worker Architecture

All workers follow a similar pattern:

1. **Initialization**: Connect to database, verify connection
2. **Main Loop**: Continuously poll for jobs
3. **Job Processing**: Fetch, process, and complete jobs
4. **Error Handling**: Log errors and mark failed jobs

## Running Workers

Workers are designed to run as systemd services:

```bash
# Enable and start a worker
sudo systemctl enable hotspot_worker.service
sudo systemctl start hotspot_worker.service

# Check status
sudo systemctl status hotspot_worker.service

# View logs
sudo journalctl -u hotspot_worker.service -f
```

## Available Workers

```{toctree}
:maxdepth: 2

hotspot_analysis
outlier_analysis
nearest_analysis
dissolve
clip
raster_clip
create_view
erase_analysis
hotspot_timeseries
```

## Worker Configuration

Workers are configured via systemd service files in the `systemd/` directory. Each service file specifies:

- Working directory
- PHP executable path
- User/group to run as
- Restart behavior
- Resource limits

## Job Processing

Workers use the `background_jobs` table to manage jobs:

- **Enqueue**: Jobs are created with status 'queued'
- **Fetch**: Workers fetch jobs using `FOR UPDATE SKIP LOCKED`
- **Process**: Workers update status to 'running' and process
- **Complete**: Workers update status to 'completed' with results
- **Error**: On failure, status set to 'failed' with error message

## Monitoring

Monitor workers via:

- Systemd logs: `journalctl -u {worker_name}.service`
- Application logs: `logs/worker_{name}.log`
- Database: Query `background_jobs` table for job status

## Related Documentation

- [Architecture Overview](../architecture.md)
- [API Documentation](../api/index.md)
- [Analysis Tools](../analysis-tools/index.md)