# haiz/threadingq architecture

> Architecture diagram of the GitHub repository haiz/threadingq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haiz/threadingq
- Repository: https://github.com/haiz/threadingq

## Overview

##### Core Components
- ThreadingQueue (Main Controller)
- WorkerThread Manager
- Queue System
- Worker Function Handler
- Async/Sync Support Layer

##### Flow Architecture
a. Producer Flow
b. Queue Management Flow
c. Worker Thread Flow
d. Resource Management Flow

##### Component Details

ThreadingQueue Controller:
- Sync Interface (put)
- Async Interface (async put)
- num_of_threads
- worker_params
- log_dir
- worker_params_builder
- on_thread_close

Queue System:
- Connection to both producer and consumer sides
- Queue state management

Worker Thread Pool:
- Multiple worker threads
- Thread lifecycle management
- Resource handling (e.g., DB connections)

##### Special Features to Highlight
- Context manager support (with/async with)
- Worker parameter building
- Thread cleanup mechanisms
- Logging system integration

##### Interactions
Key interactions:
- Producer → Queue
- Queue → Worker Threads
- Worker Threads → Resources
- Error Handling → Retry Logic

A separate section showing:
- Supported Python versions
- Threading model details
- Async/sync compatibility
- Resource management patterns

Specific Implementation Guidelines:

##### Retry mechanisms and error handling

- ThreadingQueue Controller: 20% of space
- Queue System: 30% of space
- Worker Thread Pool: 30% of space
- Resource Management: 20% of space

Remember to:
- Use consistent styling
- Version compatibility notes
- Clear boundaries between components
- Scalability aspects

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef core fill:#2374f7,stroke:#000,color:white
    classDef active fill:#4CAF50,stroke:#000,color:white
    classDef resource fill:#FFD700,stroke:#000
    classDef error fill:#FF5252,stroke:#000,color:white
    classDef config fill:#9C27B0,stroke:#000,color:white
    
    %% Main Controller Section
    TQ[ThreadingQueue Controller]:::core
    click TQ "https://github.com/haiz/threadingq/blob/main/src/threadingq/threading_queue.py"
    Config[Configuration Parameters<br>- num_of_threads<br>- worker_params<br>- log_dir<br>- worker_params_builder<br>- on_thread_close]:::config
    Version[Version Control]:::config
    click Version "https://github.com/haiz/threadingq/blob/main/src/threadingq/__version__.py"
    Init[Package Initialization]:::config
    click Init "https://github.com/haiz/threadingq/blob/main/src/threadingq/__init__.py"

    %% Interface Section
    SyncIF[Sync Interface<br>put]:::core
    AsyncIF[Async Interface<br>async put]:::core

    %% Queue System
    QS[Queue System]:::active
    QState[Queue State Management]:::active

    %% Worker Thread Section
    WTM[Worker Thread Manager]:::core
    click WTM "https://github.com/haiz/threadingq/blob/main/src/threadingq/worker_thread.py"
    WT1[Worker Thread 1]:::active
    WT2[Worker Thread 2]:::active
    WT3[Worker Thread N]:::active

    %% Resource Management
    RM[Resource Management]:::resource
    DB[(Database<br>Connections)]:::resource
    Log[Logging System]:::resource

    %% Example Implementations
    AsyncEx[Async Example]:::core
    click AsyncEx "https://github.com/haiz/threadingq/blob/main/examples/delay-print-async.py"
    LogEx[Logging Example]:::core
    click LogEx "https://github.com/haiz/threadingq/blob/main/examples/delay-print-file-logging.py"
    CloseEx[Thread Closure Example]:::core
    click CloseEx "https://github.com/haiz/threadingq/blob/main/examples/delay-print-on-close-thread.py"
    QueueEx[Queue Processing Example]:::core
    click QueueEx "https://github.com/haiz/threadingq/blob/main/examples/delay-print-queue-item-object.py"
    NestedEx[Nested Queue Example]:::core
    click NestedEx "https://github.com/haiz/threadingq/blob/main/examples/queue_inside_queue.py"

    %% Connections
    TQ --> Config
    TQ --> Version
    TQ --> Init
    TQ --> |Control| SyncIF
    TQ --> |Control| AsyncIF
    SyncIF --> |Data Flow| QS
    AsyncIF --> |Data Flow| QS
    QS --> QState
    QS --> |Distribution| WTM
    WTM --> WT1
    WTM --> WT2
    WTM --> WT3
    WT1 & WT2 & WT3 --> |Access| RM
    RM --> DB
    RM --> Log

    %% Example Connections
    AsyncIF -.-> AsyncEx
    Log -.-> LogEx
    WTM -.-> CloseEx
    QS -.-> QueueEx
    QS -.-> NestedEx

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Active Processing]:::active
        L3[Resources]:::resource
        L4[Error Handling]:::error
        L5[Configuration]:::config
    end
```
