Workers and tasks

This document explains Cinephage's worker-based architecture for background processing, task scheduling, and concurrent operations.

Overview

Cinephage performs many operations in the background to keep the UI responsive and handle time-consuming tasks efficiently. This is accomplished through a worker-based task system.

Why Background Processing?

Without background workers:

• UI freezes during long operations
• Only one task runs at a time
• User must wait for completion
• No automation possible

With background workers:

• UI remains responsive
• Multiple tasks run concurrently
• Operations queue automatically
• Full automation enabled

Architecture

Task Queue System

Cinephage uses multiple specialized worker pools:

┌─────────────────────────────────────────────────────────────┐
│                     Task Queue System                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Import Queue │  │ Search Queue │  │ Stream Queue │      │
│  │              │  │              │  │              │      │
│  │ □ □ □ □ □    │  │ □ □ □        │  │ □ □ □ □      │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │             │
│         └──────────────────┼──────────────────┘             │
│                            ▼                                │
│  ┌───────────────────────────────────────────────────────┐ │
│  │                Worker Pool Manager                     │ │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐    │ │
│  │  │Worker 1 │ │Worker 2 │ │Worker 3 │ │Worker N │    │ │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘    │ │
│  └───────────────────────────────────────────────────────┘ │
│                            │                                │
│                            ▼                                │
│  ┌───────────────────────────────────────────────────────┐ │
│  │                   Database (SQLite)                    │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Worker Pools

Cinephage maintains separate pools for different task types:

Worker Pool	Purpose	Default Workers	Use Case
Import Workers	File imports, moves, renames	5	Adding files to library
Search Workers	Indexer searches	3	Finding releases
Stream Workers	NZB streaming	10	Streaming from usenet
Scan Workers	Library scans	2	Detecting changes
Monitoring Workers	Automated tasks	5	Background monitoring
Subtitle Workers	Subtitle downloads	3	Fetching subtitles
Portal Scan Workers	Live TV portal scanning	2	Finding IPTV accounts
Channel Sync Workers	Live TV channel sync	3	Updating channel lists

Task Lifecycle

A task goes through several states:

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Pending  │───▶│ Queued   │───▶│ Running  │───▶│ Complete │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                                      │
                                      ▼
                               ┌──────────┐
                               │  Failed  │
                               └──────────┘

States Explained:

1. Pending - Task created but not yet submitted to queue
2. Queued - Task waiting for available worker
3. Running - Worker actively processing task
4. Complete - Task finished successfully
5. Failed - Task encountered an error

Task Types

Import Tasks

Handle file operations:

Operations:

• Move files from download folder
• Copy files to library
• Create hardlinks/symlinks
• Rename files according to patterns
• Extract metadata
• Update database

Duration: 1-30 seconds per file depending on:

• File size (copy vs move)
• Network speed (if network storage)
• Disk I/O performance
• Number of files

Search Tasks

Query indexers for releases:

Search Types:

• Missing Search - Find items not yet downloaded
• Cutoff Unmet - Find upgrades below quality cutoff
• Upgrade Search - Find any better quality
• Manual Search - User-initiated search

Duration: 5-30 seconds depending on:

• Number of indexers
• Indexer response time
• Network latency
• Result parsing

Streaming Tasks

Manage NZB streaming:

Operations:

• Mount NZB virtual filesystem
• Fetch segments from usenet
• Cache segments locally
• Stream to player
• Handle player requests
• Cleanup old segments

Duration: Continuous while streaming

Monitoring Tasks

Automated background operations:

Task List:

1. Missing Content Search - Find missing movies/episodes
2. Cutoff Unmet Search - Upgrade below-cutoff items
3. Upgrade Search - Find all quality upgrades
4. RSS Sync - Check indexers for new releases
5. Smart List Refresh - Update dynamic lists
6. Subtitle Search - Find missing subtitles
7. Subtitle Upgrade - Find better subtitles

Schedule: Configurable intervals (minutes to days)

Library Tasks

Maintain library consistency:

Operations:

• Library Scan - Detect new/changed/deleted files
• Metadata Refresh - Update TMDB information
• Health Check - Verify file integrity
• Cleanup - Remove orphaned database entries

Worker Configuration

Environment Variables

Control worker pools via environment:

# Docker Compose example
environment:
  # Import operations
  - WORKER_MAX_IMPORTS=5
  
  # Search operations  
  - WORKER_MAX_SEARCH=3
  
  # Streaming operations
  - WORKER_MAX_STREAMS=10
  
  # Library scanning
  - WORKER_MAX_SCANS=2
  
  # Background monitoring
  - WORKER_MAX_MONITORING=5
  
  # Subtitle operations
  - WORKER_MAX_SUBTITLE_SEARCH=3
  
  # Live TV operations
  - WORKER_MAX_PORTAL_SCANS=2
  - WORKER_MAX_CHANNEL_SYNCS=3
  
  # Maintenance
  - WORKER_CLEANUP_MS=1800000  # 30 minutes
  - WORKER_MAX_LOGS=1000        # Max log entries per worker

Tuning Guidelines

Small Setup (1-2 users, < 1000 items):

WORKER_MAX_IMPORTS=3
WORKER_MAX_SEARCH=2
WORKER_MAX_STREAMS=5
WORKER_MAX_MONITORING=3

Medium Setup (2-5 users, 1000-10000 items):

WORKER_MAX_IMPORTS=5
WORKER_MAX_SEARCH=3
WORKER_MAX_STREAMS=10
WORKER_MAX_MONITORING=5

Large Setup (5+ users, 10000+ items):

WORKER_MAX_IMPORTS=10
WORKER_MAX_SEARCH=5
WORKER_MAX_STREAMS=20
WORKER_MAX_MONITORING=10

Heavy NZB Streaming:

WORKER_MAX_STREAMS=20
WORKER_MAX_IMPORTS=8

Resource Limits

More workers consume more:

• Memory - Each worker uses 50-100MB RAM
• CPU - Concurrent processing
• Database connections - SQLite handles concurrency well but has limits
• Network connections - More indexers/API calls

Monitor resource usage when increasing workers.

Task Scheduling

Monitoring Tasks

Scheduled tasks run automatically:

┌─────────────────────────────────────────────────────────────┐
│                    Task Scheduler                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Task                    Interval    Next Run    Status     │
│  ─────────────────────────────────────────────────────────  │
│  Missing Content         6 hours     14:30       Enabled    │
│  Cutoff Unmet            Daily       02:00       Enabled    │
│  Upgrade Search          Weekly      Sun 03:00   Enabled    │
│  RSS Sync                15 min      12:45       Enabled    │
│  Smart List Refresh      6 hours     15:00       Enabled    │
│  Subtitle Search         6 hours     14:45       Enabled    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Configuring Intervals

Access Settings:

Settings > Tasks

Adjust Intervals:

1. Click on task
2. Adjust slider or enter value
3. Choose unit (minutes, hours, days)
4. Click Save

Recommended Intervals:

Task	Conservative	Balanced	Aggressive
Missing Content	12 hours	6 hours	1 hour
Cutoff Unmet	Daily	Daily	Every 6 hours
Upgrade Search	Weekly	Weekly	Daily
RSS Sync	30 min	15 min	5 min
Smart List Refresh	12 hours	6 hours	1 hour

Rate Limiting

More frequent tasks may hit indexer rate limits. Start conservative.

Task History

View task execution history:

Settings > Tasks > History

History Shows:

• Execution time
• Success/failure status
• Items processed
• Duration
• Error messages (if failed)

Monitoring Workers

Worker Status

Check worker health:

Settings > System > Workers

Status Indicators:

Status	Meaning	Action
Idle	Worker waiting for tasks	Normal
Busy	Worker processing task	Normal
Error	Worker encountered error	Check logs
Stalled	Worker not responding	Restart Cinephage

Queue Depth

Monitor task queues:

Deep Queues Indicate:

• More workers needed
• Tasks taking too long
• Resource constraints

Solutions:

1. Increase worker count
2. Check for stuck tasks
3. Review resource usage
4. Restart Cinephage

Logs

View worker activity:

# Docker
docker logs cinephage | grep -i worker

# Native
tail -f /path/to/logs/cinephage.log | grep -i worker

Log Information:

• Task start/stop times
• Worker assignments
• Processing duration
• Errors and stack traces

Task Execution Flow

Example: Import Task

1. User clicks "Import" on movie
         ↓
2. Import task created
         ↓
3. Task queued in Import Queue
         ↓
4. Import Worker picks up task
         ↓
5. Worker performs operations:
   - Validate source file
   - Apply naming pattern
   - Copy/move/hardlink file
   - Extract metadata
   - Update database
   - Notify UI
         ↓
6. Task marked Complete
         ↓
7. UI updates automatically

Example: Search Task

1. Missing Content Search task starts
         ↓
2. Query database for missing items
         ↓
3. For each missing item:
   a. Send to Search Queue
   b. Search Worker queries indexers
   c. Parse and score results
   d. Select best release
   e. Send to download client
         ↓
4. Task completes
         ↓
5. Next task scheduled

Error Handling

Task Failures

When a task fails:

1. Error logged with details
2. Task marked as Failed
3. Retry logic may apply
4. User notified (if applicable)

Automatic Retry:

Some tasks retry automatically:

• Download failures (3 attempts)
• Import failures (2 attempts)
• Network timeouts (2 attempts)

Manual Retry:

Failed tasks can be retried:

Activity > History > Failed Items > Retry

Common Failures

Failure	Cause	Solution
Import Failed	Permissions, locked file	Check permissions, retry
Search Failed	Indexer down, rate limit	Wait, check indexer health
Stream Failed	Missing segments, timeout	Try different NZB, increase timeout
Scan Failed	Path not found	Check root folder path

Performance Considerations

Concurrency Limits

SQLite handles concurrency well but has limits:

• Readers - Multiple simultaneous reads (no limit)
• Writers - One writer at a time per database

Impact:

• Import tasks may queue behind each other
• UI reads don't block on writes
• Long transactions block other writes

Memory Usage

Each worker consumes memory:

Worker Type	Memory per Worker	10 Workers
Import	50-100 MB	500-1000 MB
Search	30-50 MB	300-500 MB
Stream	100-200 MB	1000-2000 MB
Monitoring	40-60 MB	400-600 MB

Total Estimate:

• Base Cinephage: 200-500 MB
• Workers: 2-4 GB (depending on configuration)
• Cache: Configurable (10-50 GB disk)

CPU Usage

Workers use CPU when active:

• Import - High CPU during file operations
• Search - Medium CPU during parsing
• Stream - Low CPU (mostly I/O wait)
• Monitoring - Variable based on task

Tuning:

• Match worker count to CPU cores
• Leave headroom for UI and other processes
• Monitor CPU usage during peak times

Best Practices

Worker Configuration

1. Start Conservative:

   • Use default worker counts
   • Monitor performance
   • Scale up gradually

2. Match Hardware:

   • More RAM = more workers
   • More CPU cores = more workers
   • SSD storage = faster task completion

3. Monitor Resources:

   • Watch memory usage
   • Check CPU load
   • Monitor queue depths

Task Scheduling

1. Spread Tasks Out:

   • Don't schedule all tasks at once
   • Stagger start times
   • Avoid peak usage times

2. Adjust for Usage:

   • More frequent during active hours
   • Less frequent overnight
   • Pause during maintenance

3. Watch Rate Limits:

   • Indexers have limits
   • TMDB has limits
   • Don't exceed quotas

Troubleshooting

1. Stuck Workers:

   # Restart Cinephage
   docker restart cinephage

2. Queue Backlog:

   • Increase worker count
   • Check for stuck tasks
   • Review task logs

3. High Resource Usage:

   • Reduce worker counts
   • Increase task intervals
   • Optimize database

Advanced Topics

Custom Workers

Developers can add custom worker types:

// Worker definition
interface Worker {
  name: string;
  maxConcurrent: number;
  process(task: Task): Promise<void>;
}

// Task definition
interface Task {
  id: string;
  type: string;
  data: unknown;
  priority: number;
}

Worker Scaling

For high-load scenarios:

Vertical Scaling:

• More workers on same instance
• Better hardware (CPU/RAM)
• Optimized database

Horizontal Scaling (Advanced):

• Multiple Cinephage instances
• Shared database (SQLite has limitations)
• Load balancer distribution
• Not officially supported

Monitoring Integration

Export worker metrics:

environment:
  - METRICS_ENABLED=true
  - METRICS_PORT=9090

Metrics Available:

• Queue depths
• Worker utilization
• Task duration
• Error rates
• Processing throughput

See Also

• Performance Tuning - Optimize worker performance
• Environment Variables - All configuration options
• Architecture - System architecture overview
• Settings Explained - UI settings reference