Metadata-Version: 2.4
Name: py-alaska
Version: 0.1.30
Summary: ALASKA - Multiprocess Task Management Framework for Python
Author-email: DivisionVision <aainka@gmail.com>
Maintainer-email: DivisionVision <aainka@gmail.com>
License: All Rights Reserved
Project-URL: Homepage, https://github.com/DongilVision/py-alaska
Project-URL: Documentation, https://github.com/DongilVision/py-alaska
Project-URL: Repository, https://github.com/DongilVision/py-alaska
Project-URL: Issues, https://github.com/DongilVision/py-alaska/issues
Keywords: multiprocess,task,rmi,ipc,monitoring,shared-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: PySide6>=6.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: pyserial>=3.5
Requires-Dist: Pillow>=9.0.0
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: monitor
Requires-Dist: psutil>=5.8.0; extra == "monitor"
Provides-Extra: camera
Requires-Dist: PySide6>=6.0.0; extra == "camera"
Requires-Dist: opencv-python>=4.5.0; extra == "camera"
Provides-Extra: qt
Requires-Dist: PySide6>=6.0.0; extra == "qt"
Provides-Extra: all
Requires-Dist: psutil>=5.8.0; extra == "all"
Requires-Dist: PySide6>=6.0.0; extra == "all"
Requires-Dist: opencv-python>=4.5.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# ALASKA v2.7

**A**dvanced **L**ightweight **A**synchronous **S**ervice **K**ernel for **A**pplications

[![PyPI version](https://badge.fury.io/py/py-alaska.svg)](https://badge.fury.io/py/py-alaska)
[![Python](https://img.shields.io/pypi/pyversions/alaska.svg)](https://pypi.org/project/py-alaska/)
[![License](https://img.shields.io/badge/License-All%20Rights%20Reserved-red.svg)](#license)

Python 멀티프로세스 태스크 관리 프레임워크.
RMI(Remote Method Invocation), 공유 메모리 IPC(SmRingBuffer, SmBlock), TSignal(QoS), DeviceProperty 기반의 산업용 제어 시스템 구축을 지원합니다.

## Features

- **[`@task` 데코레이터](src/py_alaska/core/task_decorator.py)**: 클래스 하나로 process/thread 태스크 정의
- **[RMI](src/py_alaska/core/_rmi_client.py)**: SmRingBuffer + 바이너리 프로토콜 기반 프로세스 간 메서드/프로퍼티 호출 (avg 0.039ms)
- **[TSignal](src/py_alaska/core/task_signal_decl.py)**: 선언형 Signal 변수 — `@on(Camera.frame_raw)` 타입 안전 구독 (v2.7)
- **[SmRingBuffer](src/py_alaska/sm_infra/sm_ring_buffer.py)**: Lock-free SPSC 링 버퍼 — struct+memoryview 기반 무할당 IPC
- **[SmBlock](src/py_alaska/sm_infra/sm_block.py)**: 공유 메모리 기반 Zero-copy 이미지 전송 (numpy 배열)
- **[SignalBroker](src/py_alaska/core/task_signal.py)**: QoS 우선순위 Pub/Sub — CRITICAL(P1) ~ BACKGROUND(P5)
- **[SmSignalRegistry](src/py_alaska/sm_infra/sm_signal.py)**: 공유 메모리 비트맵 기반 구독자 레지스트리 (조회 avg 2.6μs)
- **[SmMutex / SmKernelEvent](src/py_alaska/sm_infra/sm_sync.py)**: Win32 Named Mutex 및 커널 이벤트 동기화
- **[DeviceProperty](src/py_alaska/device/device_property.py)**: 선언형 HW 속성 관리 (캐시, opstate, resync, debounce, rollback)
- **[Qt 통합](src/py_alaska/qt/app.py)**: `AlaskaApp.run()`으로 PySide6 UI 태스크 지원
- **[Web 모니터링](src/py_alaska/monitor/task_monitor.py)**: HTTP 기반 실시간 대시보드 (태스크 상태, RMI 통계, CPU/메모리)
- **Auto-restart**: 태스크 장애 시 자동 복구
- **[JSON 설정](src/py_alaska/core/gconfig.py)**: `@import` 기반 태스크 클래스 자동 탐지 및 속성 주입

## History

| 버전 | 시기 | 주요 내용 |
|------|------|----------|
| v1.x | 2024 | 최초 개발 — multiprocessing 기반 Task 관리, RMI, Signal Pub/Sub |
| v2.0 | 2026-01 | 전면 재설계 — SmRingBuffer(Lock-free SPSC), SmBlock(Zero-copy), SmSignalRegistry(공유 메모리 비트맵) |
| v2.3 | 2026-02 | DeviceProperty, SmBlackBox, QoS 우선순위 스케줄러 |
| v2.6 | 2026-03 | SmInfra 최적화(M-01~M-10) — struct+memoryview, DirectClient, binary RMI protocol |
| v2.7 | 2026-03 | TSignal 선언형 Signal 변수, `@on()` 데코레이터 — `@rmi_signal` / `signal_subscribe` 제거 |

## Installation

```bash
pip install py-alaska
```

## Quick Start

### 1. 태스크 정의

```python
from py_alaska import task
from py_alaska.core.task_signal_decl import TSignal, on

@task(mode="process", restart=True)
class Sensor:
    temperature = TSignal(float, name="sensor.temp")  # 선언형 Signal

    def run(self):
        while self.running:
            self.temperature.emit(self._read())   # emit

    def _read(self):
        return 25.0

@task(mode="thread")
class Monitor:
    @on(Sensor.temperature)                       # 타입 안전 구독
    def on_temp(self, signal):
        print(f"Temp: {signal.data}°C")
```

### 2. 설정 파일 (config.json)

```json
{
  "app_info": {"name": "MyApp", "id": "myapp_001", "version": "1.0.0"},
  "task_config": {
    "sensor/Sensor": {"@import": "my_tasks"},
    "monitor/Monitor": {"@import": "my_tasks"}
  }
}
```

### 3. 실행

```python
from py_alaska import TaskManager, gconfig

gconfig.load("config.json")
manager = TaskManager(gconfig)
manager.start_all()

client = manager.get_client("sensor")
print(client._read())   # RMI: 프로세스 간 메서드 호출
```

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                          TaskManager                             │
├──────────────────────────────────────────────────────────────────┤
│  ┌────────────┐    ┌────────────┐    ┌────────────┐              │
│  │  Task A    │    │  Task B    │    │  Task C    │              │
│  │ (Process)  │    │ (Process)  │    │ (Thread)   │              │
│  │ RmiClient  │    │ DEVICE     │    │  QWidget   │              │
│  │            │    │ PROPERTY   │    │DirectClient│              │
│  └─────┬──────┘    └─────┬──────┘    └─────┬──────┘              │
│        └─────────────────┼─────────────────┘                     │
│                          │                                       │
│            ┌─────────────┴──────────────┐                        │
│            │  InvokeDispenser           │                        │
│            │  (Signal + RMI 통합 디스패처) │                        │
│            └─────────────┬──────────────┘                        │
│                          │                                       │
│     ┌────────────────────┼────────────────────┐                  │
│  ┌──┴──────────┐  ┌──────┴──────┐  ┌─────────┴──┐               │
│  │SmRingBuffer │  │SignalBroker │  │  SmBlock   │               │
│  │(Lock-free   │  │(QoS P1~P5  │  │ (Zero-copy │               │
│  │ SPSC IPC)   │  │+TSignal    │  │  numpy)    │               │
│  │+RmiProtocol │  │+SmSignal   │  │            │               │
│  │ (Binary)    │  │  Registry  │  │            │               │
│  └─────────────┘  └────────────┘  └────────────┘               │
│                                                                  │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐                 │
│  │ SmMutex    │  │SmKernel   │  │  GConfig   │                 │
│  │(Win32 Named│  │  Event    │  │(JSON/YAML) │                 │
│  │ Mutex)     │  │(동기화)    │  │            │                 │
│  └────────────┘  └────────────┘  └────────────┘                 │
├──────────────────────────────────────────────────────────────────┤
│  TaskMonitor (HTTP :7000)  │  TaskProfiler  │  SmBlackBox       │
└──────────────────────────────────────────────────────────────────┘
```

## Performance (v2.7, 2026-04-25)

| 항목 | 설명 | avg | p50 | p99 |
|------|------|-----|-----|-----|
| PM-01 | RMI round-trip | **0.039ms** | 0.036ms | 0.091ms |
| PM-02 | Signal P→T | **0.072ms** | 0.068ms | 0.165ms |
| PM-04 | Nowait RMI TPS | **23,738** | — | — |
| PM-05 | Multi-task TPS | **23,348** | — | — |
| PM-07 | Registry Lookup | **2.6μs** | 2.5μs | 4.2μs |
| PM-09 | Signal Ping-pong | **0.101ms** | 0.098ms | 0.159ms |
| PM-10 | 3-Hop RMI | **0.181ms** | 0.176ms | 0.269ms |
| PM-11 | 3-Hop Signal | **0.204ms** | 0.188ms | 0.309ms |
| PM-12 | Pure Signal Ping | **0.174ms** | 0.175ms | 0.316ms |

## Core API

### @task 데코레이터

```python
@task(
    name="task_name",      # 태스크 식별자 (생략 시 클래스명 사용)
    mode="process",        # "process" | "thread"
    restart=True,          # 장애 시 자동 재시작
    restart_delay=1.0,     # 재시작 대기 시간 (초)
)
class MyTask:
    def run(self):         # 메인 실행 루프
        while self.running:
            pass
```

- 모든 public 메서드가 RMI 대상
- `self.running`: 실행 상태 플래그
- `self.signal`: Signal 클라이언트
- `self.task_name`: 등록된 태스크 ID

### TSignal (v2.7)

선언형 Signal 변수. 클래스 변수로 선언하면 emit 목록이 명시적으로 드러나고, `@on()`으로 타입 안전 구독이 가능합니다.

```python
from py_alaska.core.task_signal_decl import TSignal, on

@task()
class Camera:
    frame_raw = TSignal(dict, name="camera.frame_raw")    # 선언
    connected = TSignal(bool, name="camera.connected")

    def run(self):
        while self.running:
            frame = self.capture()
            self.frame_raw.emit({"index": frame_idx})     # emit

@task()
class Viewer:
    @on(Camera.frame_raw)                                 # 타입 안전 구독
    def on_frame(self, signal):
        idx = signal.data["index"]

    @on(Camera.connected)
    @ui_thread                                            # Qt UI 스레드 전환
    def on_connected(self, signal):
        self.btn.setEnabled(signal.data)
```

### RMI (Remote Method Invocation)

SmRingBuffer + 바이너리 프로토콜 기반 프로세스 간 투명 호출.
Thread 모드에서는 DirectClient로 IPC 없이 직접 호출합니다.

```python
# 동기 호출 (반환값 있음)
result = self.worker.process(data)

# 비동기 호출 (fire-and-forget)
self.worker.process.nowait(data)

# 프로퍼티 RMI
self.camera.exposure = 15000    # setter
value = self.camera.exposure    # getter
```

### SmBlock (Zero-copy 이미지 전송)

```json
{
  "platform_config": {
    "_smblock": {
      "image_pool": {"shape": [1024, 1024, 3], "maxsize": 100}
    }
  }
}
```

```python
index = self.smblock.alloc()             # 블록 할당
buf = self.smblock.get_buffer(index)     # numpy 배열 참조 (Zero-copy)
buf[:] = frame_data                      # 직접 쓰기
self.smblock.mfree(index)               # 해제
```

### DeviceProperty

HW 속성을 선언형으로 관리합니다. 캐시, 타입 변환, opstate, resync, debounce, HW 실패 시 cache rollback을 자동 처리합니다.

```python
from py_alaska.device.device_property import DeviceProperty

@task(mode="process")
class CameraDriver:
    exposure = DeviceProperty(
        dtype=int, default=15000,
        setter="_hw_set_exposure",
        debounce=0.5,
    )
    trigger_mode = DeviceProperty(
        dtype=bool, default=False,
        setter="_hw_set_trigger",
    )
```

## Config (JSON)

```json
{
  "app_info": {"name": "MyApp", "id": "node-001", "version": "1.0.0"},
  "platform_config": {
    "_smblock": {"pool": {"shape": [1024, 1024, 3], "maxsize": 100}},
    "_monitor": {"port": 7000, "exit_hook": true}
  },
  "task_config": {
    "group/task_name": {
      "@import": "module.path",
      "property1": "value1",
      "client_ref": "client:other_task"
    }
  }
}
```

- `@import`: 태스크 클래스가 위치한 모듈 경로
- `group/task_name`: `group`은 논리 그룹, `task_name`은 `@task(name=...)` 이름
- `client:task_id`: RMI 프록시 자동 주입
- `smblock:pool_name`: SmBlock 인스턴스 자동 주입

## Examples

| 예제 | 설명 |
|------|------|
| [`ex010_hello_world`](example/ex010_hello_world) | 최소 태스크 정의 및 실행 |
| [`ex020_debug`](example/ex020_debug) | 디버그 모드 |
| [`ex030_profiler`](example/ex030_profiler) | 태스크 프로파일러 |
| [`ex040_restart`](example/ex040_restart) | 장애 시 자동 재시작 |
| [`ex050_select_signal`](example/ex050_select_signal) | Signal 선택적 구독 |
| [`ex060_dynamic_signal`](example/ex060_dynamic_signal) | 동적 Signal 구독 |
| [`ex070_chain_call`](example/ex070_chain_call) | RMI 체인 호출 |
| [`ex080_persistent`](example/ex080_persistent) | 영구 설정 (GConfig) |
| [`ex090_signal_rmi_combo`](example/ex090_signal_rmi_combo) | Signal + RMI 혼합 |
| [`ex091_property_rmi`](example/ex091_property_rmi) | 프로퍼티 RMI |
| [`ex100_direct_update_ui`](example/ex100_direct_update_ui) | Qt UI 직접 업데이트 |
| [`ex110_smblock`](example/ex110_smblock) | SmBlock 공유 메모리 IPC |
| [`ex120_task`](example/ex120_task) | 태스크 고급 패턴 |
| [`ex130_camera`](example/ex130_camera) | IMI 카메라 (CamProperty) |
| [`ex130a_camera`](example/ex130a_camera) | IMI 카메라 (DeviceProperty) |
| [`ex130b_camera_webcam`](example/ex130b_camera_webcam) | 웹캠 |
| [`ex140_performance`](example/ex140_performance) | 성능 측정 |
| [`ex150_dynamic_task`](example/ex150_dynamic_task) | 동적 태스크 생성/제거 |
| [`ex160_device_property`](example/ex160_device_property) | DeviceProperty 데모 |
| [`ex170_web_debugger`](example/ex170_web_debugger) | 웹 디버거 |
| [`ex180_JoyStick`](example/ex180_JoyStick) | 조이스틱 제어 |
| [`ex510_save_image`](example/ex510_save_image) | 이미지 저장 |

## Monitoring

`http://localhost:7000` (설정 포트)에서 웹 대시보드 접근.

- 태스크 상태 (alive/stopped/restart 횟수)
- RMI 호출 통계 (횟수, 응답시간 min/avg/max)
- Signal 통계 (Latency, TPS, QoS 위반)
- CPU/메모리 사용량 (psutil)
- SmBlock 풀 사용률
- 런타임 설정 편집 / 변수 조회

## Repository Structure

```
2026_0130_alask_v2/
├── src/py_alaska/             # 패키지 소스
├── example/                   # 실행 가능한 예제 (ex010 ~ ex510)
├── tests/                     # 자동화 시험
│   ├── test_0_sm_infra*.py    # SmInfra 단위·경합·성능 시험
│   ├── test_1_*.py            # IPC / Signal 통합 시험
│   └── archive/               # 구버전 시험 (v2.0~v2.3)
├── docs/                      # 설계 문서
│   ├── core/                  # SmInfra 설계 · 성능 · 수정계획
│   ├── task/                  # Task 시스템 · 생명주기 · IPC/Signal 사용
│   ├── monitor/               # 디버그 · 웹디버거
│   ├── app/                   # 예제 · 응용 설계
│   ├── operation/             # 개발자 가이드 · 수정이력 · 코드리뷰
│   └── reports/               # 성능 측정 결과
├── divnote-mcp/               # Divnote MCP 서버 (Node.js)
├── onai/                      # AI 프롬프트 도구
└── x_deploy_tool/             # 배포 유틸리티
```

## Module Structure

```
py_alaska/
│
├── core/                      ← 핵심 태스크 실행 프레임워크
│   │
│   ├── [Public API]
│   ├── task_manager.py        # TaskManager — 태스크 등록·시작·정지·재시작
│   ├── task_signal.py         # SignalBroker, SignalClient, SubscriberCache
│   ├── task_signal_decl.py    # TSignal, BoundTSignal, @on 데코레이터  ← v2.7
│   ├── task_decorator.py      # @task, @rmi_task 데코레이터
│   ├── gconfig.py             # GConfig — JSON/YAML 설정 싱글턴
│   ├── task_error.py          # 사용자 친화적 에러 메시지 + 예외 클래스
│   ├── task_performance.py    # IpcMeasurement — RMI/Signal 성능 메트릭
│   ├── task_profiler.py       # TaskProfiler — 코드 블록 실행 시간 측정
│   └── task_log.py            # RmiLogger, LogTask — 중앙 로깅 시스템
│   │
│   └── [Internal]
│       ├── _rmi_client.py     # RmiProtocol(바이너리), RmiClient, DirectClient
│       ├── _signal_core.py    # QoS 프리셋, Signal dataclass, PriorityScheduler
│       ├── _task_runtime.py   # TaskRuntime + InvokeDispenser (Signal+RMI 통합 디스패처)
│       ├── _task_validator.py # @task 선언 검증 (순환 의존 등)
│       ├── _config_infra.py   # GConfig 예외 11종, FileLock, PathParser
│       ├── _log_handler.py    # 멀티프로세스 안전 RotatingFileHandler
│       └── _comm_utils.py     # 디버그 포맷, 체인 감지, 비동기 워커
│
├── sm_infra/                  ← 공유 메모리 인프라 (L0~L3 계층)
│   ├── _base.py               # _ShmBase — 모든 SHM 클래스 공통 기반
│   ├── sm_ring_buffer.py      # SmRingBuffer — Lock-free SPSC (struct+memoryview)
│   ├── sm_block.py            # SmBlock — Zero-copy 이미지 블록 풀 (numpy)
│   ├── sm_value.py            # SmValue — 프로세스 간 고속 스칼라 공유
│   ├── sm_queue.py            # SmQueue — SmRingBuffer + Event 기반 IPC 큐
│   ├── sm_signal.py           # SmSignalRegistry(비트맵), SmSignalStats(통계)
│   ├── sm_blackbox.py         # SmBlackBox — Signal 체인 세션 감시·경보
│   └── sm_sync.py             # SmKernelEvent(Win32), SmLockFreeEvent, SmMutex
│
├── device/                    ← 디바이스 속성 관리
│   ├── device_property.py     # DeviceProperty — Python descriptor 기반 HW 속성
│   ├── device_schema.py       # 키 파싱 ("name:dtype=default"), 조건 파싱
│   └── device_infra.py        # DeviceTaskMixin — 캐시·타이머·resync 인프라
│
├── qt/                        ← Qt(PySide6) UI 통합
│   ├── app.py                 # AlaskaApp.run() — Qt 앱 진입점
│   ├── decorators.py          # @ui_thread — UI 스레드 안전 실행
│   ├── tab_camera.py          # TabCamera — 카메라 뷰어 위젯
│   └── _zoom_view.py          # ZoomView, CameraView — 확대/관심영역 뷰
│
├── monitor/                   ← HTTP 웹 모니터링 대시보드
│   ├── task_monitor.py        # TaskMonitor — HTTP 서버, REST API, 실시간 대시보드
│   ├── task_monitor_sysinfo.py# HwInfoCollector — CPU/메모리/네트워크 수집
│   ├── task_monitor_ext_link.py# Slack/Email/Webhook 외부 연동, 스케줄러
│   ├── task_monitor_html.py   # 대시보드 HTML 템플릿
│   ├── task_monitor_debug_html.py # 디버그 뷰 HTML
│   └── task_monitor_css.py    # 스타일시트
│
└── drives/                    ← 하드웨어 드라이버
    └── imi/                   # IMI(동일비전) 카메라 드라이버
        ├── Neptune_API.py     # NeptuneC DLL Python 바인딩
        └── imi_camera.py      # ImiCamera — SmBlock 연동 카메라 태스크
```

## Requirements

- Python >= 3.10
- numpy
- opencv-python (optional)
- PySide6 (optional, Qt UI)
- psutil (optional, 시스템 모니터링)

## License

Copyright (c) 동일비전(Dongil Vision Korea). All Rights Reserved.
무단 복제 및 배포를 금지합니다. 연구 목적의 개인 사용은 허용됩니다.
