taskController 0.2.2

A Python library for pause/resume/kill control of functions across processes

TaskController

A Python library for pause/resume/kill control of functions across processes using file-based IPC.

Features

• Pause/Resume: Pause function execution and resume later from saved state
• Kill: Terminate function execution gracefully
• Cross-Process: Control functions running in different terminals/processes
• Per-Function Control: Control multiple decorated functions independently
• CLI Tool: Control functions directly from terminal using taskController command
• Simple API: Easy-to-use decorator and control flags

Installation

pip install taskController

This installs both the Python library and the taskController CLI command.

Quick Start

Basic Usage

from taskcontroller import task_controller, controller
import time

@task_controller
def long_running_task():
    for i in range(100):
        print(f"Step {i}")
        time.sleep(1)

# Run the task
long_running_task()

Controlling from CLI (New in v0.2.0!)

# List all running functions (like 'ps')
taskController ps

# Pause a specific function
taskController stop long_running_task

# Resume a specific function
taskController resume long_running_task

# Kill a specific function
taskController kill long_running_task

# See detailed status
taskController status

Controlling from Another Terminal (Python API)

from taskcontroller import controller

# NEW: Per-function control
controller.stop_function('long_running_task')    # Pause specific function
controller.resume_function('long_running_task')  # Resume specific function
controller.kill_function('long_running_task')    # Kill specific function

# Control all functions
controller.stop_all()     # Pause all
controller.resume_all()   # Resume all
controller.kill_all()     # Kill all

# Query functions
controller.list_functions()              # List all registered functions
controller.status('long_running_task')   # Check specific function status
controller.status()                      # Check all functions

# Legacy API (still supported - affects all functions)
controller.stop = True
controller.resume = True
controller.kill = True

# Check status
print(controller.status())

# Reset all flags
controller.reset()

API Reference

Decorator

@task_controller

Wraps a function to enable pause/resume/kill control.

@task_controller
def my_function():
    # Your code here
    pass

CLI Commands (New in v0.2.0!)

taskController ps                    # List all running functions with PID/status
taskController stop <func_name>      # Pause a specific function
taskController resume <func_name>    # Resume a specific function  
taskController kill <func_name>      # Kill a specific function
taskController stop-all              # Pause all functions
taskController resume-all            # Resume all functions
taskController kill-all              # Kill all functions
taskController status [func_name]    # Show detailed status
taskController reset                 # Reset all flags

See CLI_USAGE.md for detailed CLI documentation.

Controller Methods

Per-Function Control (New in v0.2.0!)

controller.stop_function(func_name)

Pause a specific function by name.

controller.stop_function('my_function')

controller.resume_function(func_name)

Resume a specific function by name.

controller.resume_function('my_function')

controller.kill_function(func_name)

Kill a specific function by name.

controller.kill_function('my_function')

controller.stop_all()

Pause all registered decorated functions.

controller.stop_all()

controller.resume_all()

Resume all registered decorated functions.

controller.resume_all()

controller.kill_all()

Kill all registered decorated functions.

controller.kill_all()

controller.list_functions()

List all registered decorated functions with their PIDs.

functions = controller.list_functions()
# Returns: {'func_name': {'pid': 12345, 'registered_at': 1234567890.123}}

controller.status(func_name=None)

Get status of specific function or all functions.

# Specific function
status = controller.status('my_function')

# All functions
status = controller.status()

Legacy Global Control (Deprecated)

controller.stop

Set to True to pause all functions (deprecated - use stop_all() or stop_function()).

controller.stop = True

controller.resume

Set to True to resume all functions (deprecated - use resume_all() or resume_function()).

controller.resume = True

controller.kill

Set to True to terminate all functions (deprecated - use kill_all() or kill_function()).

controller.kill = True

controller.reset()

Reset all flags to default state.

controller.reset()

How It Works

• File-based IPC: Control flags are stored in /tmp/flow_control_flags/control_flags.json
• Function Registry: Active functions are tracked in /tmp/flow_control_flags/function_registry.json
• Per-Function Flags: Each function has its own control flags stored as {func_name: bool}
• State Persistence: Function state is saved to /tmp/task_controller_states/ using dill serialization
• Line-level Monitoring: Uses Python's sys.settrace() to check flags at every line of execution
• Timeout: Paused execution times out after 15 minutes

Examples

See the examples directory for complete usage examples:

• example_usage.py - Basic single function example
• example_multi_function.py - Multiple functions running concurrently
• control.py - Python-based control script
• test_per_function_control.py - Automated tests

Documentation

• CLI_USAGE.md - Detailed CLI command documentation
• PER_FUNCTION_CONTROL.md - Per-function control implementation details

Advanced Features

Multiple Functions Independent Control

Control multiple decorated functions independently - pause one while others continue running.

CLI Integration

Use the taskController command from your terminal for easy process management.

Pause with 15-Minute Timeout

When paused, execution automatically terminates if not resumed within 15 minutes.

State Preservation

Function state (local variables, execution line) is saved when paused and can be restored on resume.

Requirements

• Python >= 3.7
• dill >= 0.3.0

Version History

v0.2.0

• Added per-function control (stop/resume/kill specific functions)
• Added CLI tool (pycontroller command)
• Added function registry tracking
• Added list_functions() and enhanced status() methods
• Backward compatible with v0.1.0 API

v0.1.0

• Initial release with global stop/resume/kill control

License

MIT License

Contributing

Contributions are welcome! Please submit issues and pull requests on GitHub.