py-alaska 0.1.30

ALASKA - Multiprocess Task Management Framework for Python

ALASKA v2.7

Advanced Lightweight Asynchronous Service Kernel for Applications

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

Features

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

pip install py-alaska

Quick Start

1. 태스크 정의

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)

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

3. 실행

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 데코레이터

@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()으로 타입 안전 구독이 가능합니다.

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 없이 직접 호출합니다.

# 동기 호출 (반환값 있음)
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 이미지 전송)

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

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을 자동 처리합니다.

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)

{
  "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	최소 태스크 정의 및 실행
ex020_debug	디버그 모드
ex030_profiler	태스크 프로파일러
ex040_restart	장애 시 자동 재시작
ex050_select_signal	Signal 선택적 구독
ex060_dynamic_signal	동적 Signal 구독
ex070_chain_call	RMI 체인 호출
ex080_persistent	영구 설정 (GConfig)
ex090_signal_rmi_combo	Signal + RMI 혼합
ex091_property_rmi	프로퍼티 RMI
ex100_direct_update_ui	Qt UI 직접 업데이트
ex110_smblock	SmBlock 공유 메모리 IPC
ex120_task	태스크 고급 패턴
ex130_camera	IMI 카메라 (CamProperty)
ex130a_camera	IMI 카메라 (DeviceProperty)
ex130b_camera_webcam	웹캠
ex140_performance	성능 측정
ex150_dynamic_task	동적 태스크 생성/제거
ex160_device_property	DeviceProperty 데모
ex170_web_debugger	웹 디버거
ex180_JoyStick	조이스틱 제어
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. 무단 복제 및 배포를 금지합니다. 연구 목적의 개인 사용은 허용됩니다.