개발부터 자유까지

클로드 코드 사용법(feat. Terminal)

ssehuun — Wed, 1 Apr 2026 18:00:49 +0900

개인적으로 터미널에서 사용할때의 사용법을 익히고자 정리한다.

클로드 코드 설치

macOS, Linux, WSL 설치 명령어

curl -fsSL https://claude.ai/install.sh | bash

claude code 시작 명령어

cd your-project
claude

필수명령

명령	기능	예시
claude	대화형 모드 시작	claude
! for "bash command"	bash 명령어 동작	!cd work
/ for "claude command"	claude 명령어 동작	/help
@ for "file path"	작업 디렉토리의 파일 언급	@/work/agent.py
claude "task"	일화성 작업 실행	claude "fix the build error"
exit	claude code 종료	exit
/clear	대화기록 지우기	/clear

[Python] time 함수 비교

ssehuun — Tue, 10 Feb 2026 10:55:50 +0900

아래는 time.time() / time.perf_counter() / time.process_time() / time.monotonic() 네 가지 타이머 함수의 정확한 차이점 정리입니다.

전체 비교표

함수	목적	증가 방식	시스템 시간 변경 영향	일시정지 (절전) 영향	CPU 시간 기준	정밀도	사용 용도
time.time()	현재 시각 확인 (Unix timestamp)	실제 시간 기준	✔ 영향 받음 (NTP 동기화 등)	✔ 영향 받음	✖	중	현재 시각 출력, 로깅
time.perf_counter()	가장 정확한 성능 측정용	모노토닉 타이머	✖ 영향 없음	✖ 영향 없음	✖	매우 높음	코드 실행 시간 측정(성능 테스트)
time.process_time()	CPU 사용 시간 측정	CPU가 작업한 시간만 증가	✖ 영향 없음	✖ 영향 없음	✔ CPU time only	높음	알고리즘 CPU 사용량 측정
time.monotonic()	뒤로 되돌아가지 않는 시간 측정	모노토닉 타이머	✖ 영향 없음	✖ 영향 없음	✖	높음	경과 시간 측정(시계 튐 방지)

1. time.time()

✔ 특징

현재 시간을 초 단위 float로 반환 (UNIX timestamp)
가장 일반적인 시간 함수
시스템 시간 변경에 영향을 받음
→ NTP 동기화 / 관리자 설정 변경하면 값이 앞뒤로 튈 수 있음
정확한 소요 시간 측정용으로는 부적합

✔ 예시

import time
print(time.time()) # 1739193812.12345

2. time.perf_counter()

✔ 특징

Python에서 가장 정밀도가 높은 고해상도 타이머
부팅 후 증가하는 시간(정확한 소요 시간을 측정)
시스템 시간 변경, 절전, 일시정지에 영향 없음
성능 측정(benchmark)에 가장 적합한 함수

✔ 활용 예

start = time.perf_counter()
# 수행 코드
end = time.perf_counter()

print(end - start)

3. time.process_time()

✔ 특징

CPU가 실제로 사용된 시간만 증가
sleep(), I/O 대기 등 CPU 사용이 없는 시간은 카운트되지 않음
절전, 시스템 시간 변경, real-time 흐름과 무관
알고리즘의 CPU 소모량 측정에 적합

✔ 예시

import time

start = time.process_time()
# CPU 많이 쓰는 작업
end = time.process_time()

print(end - start)  # CPU가 실제로 사용된 시간만 출력됨

4. time.monotonic()

✔ 특징

절대로 뒤로 가지 않는(monotonic) 타이머
시스템 시간 변경 영향 없음
perf_counter보다 정밀도가 낮을 수 있지만 목적은 동일:
→ 경과 시간 측정용
perf_counter()와 비슷하지만 보장하는 정밀도는 플랫폼마다 다름
→ 일반적으로 perf_counter()가 좀 더 고정밀

✔ 예시

import time

start = time.monotonic()
# some work
end = time.monotonic()

print(end - start)

언제 어떤 걸 써야 하나?

✔ 현재 시각을 알고 싶다

→ time.time()

✔ 코드 실행 시간을 정확하게 측정하고 싶다 (benchmark)

→ time.perf_counter() (가장 추천)

✔ 알고리즘이 CPU를 얼마나 썼는지 알고 싶다

→ time.process_time()

✔ 시스템 시간 변경에도 영향을 받지 않는 경과 시간 측정

→ time.monotonic()

[Database] PostgreSQL 오류

ssehuun — Wed, 21 Jan 2026 21:13:14 +0900

https://blog.naver.com/ohj3423/223008733976

MCP 구조 이해하기

ssehuun — Fri, 16 Jan 2026 11:04:18 +0900

1. MCP 개념정리

2. MCP 아키텍처 이해하기

1. MCP 개념정리

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.

MCP는 AI 앱이 외부 시스템과 통신하기 위한 규약을 구현한 오픈소스이다.

MCP를 이용하면 ChatGPT나 클로드 같은 AI 앱이 로컬 파일이나 DB의 데이터에 접근할 수 있고, 검색 엔진이나 계산기 같은 툴을 사용할 수 있고, 특화된 프롬프트를 통해 워크플로우가 특정 정보에 접근하여 태스크를 수행할 수 있게 한다.

AI앱을 위한 USB-C 포트라고 생각하면 된다. USB-C 포트가 전자 기기의 표준화된 방식을 제공하는 것처럼, MCP는 AI앱이 외부 시스템에 접근할 수 있는 표준화된 방식을 제공한다.

1-1. MCP는 무엇을 할 수 있는가

에이전트가 구글 캘린더, 노션에 접근하여 개인화된 AI 도구처럼 실행할 수 있게 도와준다
클로드 코드가 피그마 디자인을 통해 웹앱을 생성해준다
기업용 챗봇이 조직의 여러 DB에 접근하여 사용자들이 채팅으로 데이터를 분석할 수 있게 도와준다
블랜더(3D SW)위에서 AI 모델들이 3D 디자인을 생성하고 3D 프린터로 만들어낼 수 있다

1-2. 왜 MCP는 중요한가

생태계에서 어떤 위치에 있느냐에 따라 MCP는 다양한 이점을 제공할 수 있습니다.

개발자 - MCP는 AI 애플리케이션이나 에이전트를 구축하거나 통합할 때 개발 시간과 복잡성을 줄여줍니다.
AI 애플리케이션 또는 에이전트 - MCP는 데이터 소스, 도구, 앱의 생태계에 접근할 수 있게 하여 기능을 강화하고 최종 사용자 경험을 향상시킵니다.
최종 사용자 - MCP는 사용자의 데이터를 액세스하고 필요할 때 사용자를 대신해 작업을 수행할 수 있는, 보다 강력한 AI 애플리케이션이나 에이전트를 제공합니다.

2. MCP 아키텍처 이해하기

2-1. MCP의 컨셉

2-1-1. 참여자

MCP는 클라이언트-서버 아키텍처를 따릅니다.
MCP 호스트(예: Claude Code, Claude Desktop)는 하나 이상의 MCP 서버에 연결을 설정합니다.
이때 MCP 호스트는 각 MCP 서버마다 하나의 MCP 클라이언트를 생성하며, 각 클라이언트는 해당 서버와의 전용 연결을 유지합니다.

로컬 MCP 서버(STDIO 전송 사용)는 일반적으로 단일 클라이언트를 서비스합니다.
원격 MCP 서버(Streamable HTTP 전송 사용)는 여러 클라이언트를 동시에 서비스할 수 있습니다.

핵심 참여자:

MCP 호스트: 하나 이상의 MCP 클라이언트를 관리하고 조정하는 AI 애플리케이션
MCP 클라이언트: MCP 서버와의 연결을 유지하며, MCP 호스트가 사용할 컨텍스트를 가져오는 구성 요소
MCP 서버: MCP 클라이언트에 컨텍스트를 제공하는 프로그램

예시:
Visual Studio Code는 MCP 호스트로 작동합니다.
VS Code가 Sentry MCP 서버에 연결하면, VS Code 런타임은 해당 서버와의 연결을 유지하는 MCP 클라이언트 객체를 생성합니다. 또한 로컬 파일시스템 서버에 연결할 때는 또 다른 MCP 클라이언트 객체를 생성합니다.

MCP 서버는 실행 위치와 관계없이 컨텍스트 데이터를 제공하는 프로그램을 의미합니다.
예를 들어 Claude Desktop이 파일시스템 서버를 실행하면, STDIO 전송을 사용하므로 동일한 머신에서 로컬로 실행됩니다. 반면 Sentry MCP 서버는 Sentry 플랫폼에서 원격으로 실행되며 Streamable HTTP 전송을 사용합니다.

2-1-2. 계층 (Layers)

MCP는 두 개의 계층으로 구성됩니다:

데이터 계층 (Data Layer): JSON-RPC 기반의 클라이언트-서버 통신 프로토콜을 정의하며, 생명주기 관리 및 도구(tools), 리소스(resources), 프롬프트(prompts), 알림(notifications) 등의 핵심 요소를 포함합니다.
전송 계층 (Transport Layer): 클라이언트와 서버 간의 데이터 교환을 가능하게 하는 통신 메커니즘과 채널을 정의합니다. 연결 설정, 메시지 프레이밍, 인증 등을 포함합니다.

데이터 계층은 내부 계층, 전송 계층은 외부 계층으로 개념화됩니다.

데이터 계층 (Data Layer)

데이터 계층은 JSON-RPC 2.0 기반의 교환 프로토콜을 구현합니다. 이 계층은 다음을 포함합니다:

생명주기 관리: 클라이언트와 서버 간의 연결 초기화, 기능 협상, 연결 종료를 처리합니다.
서버 기능: AI 동작을 위한 도구, 컨텍스트 데이터 리소스, 상호작용 템플릿 프롬프트 등을 제공합니다.
클라이언트 기능: 서버가 클라이언트의 LLM 샘플링, 사용자 입력 요청, 로그 메시지 전송 등을 요청할 수 있게 합니다.
유틸리티 기능: 실시간 업데이트 알림, 장기 실행 작업의 진행 상태 추적 등을 지원합니다.

전송 계층 (Transport Layer)

전송 계층은 클라이언트와 서버 간의 통신 채널 및 인증을 관리합니다. 연결 설정, 메시지 프레이밍, 보안 통신을 담당합니다. MCP는 두 가지 전송 방식을 지원합니다:

STDIO 전송: 동일한 머신 내의 프로세스 간 표준 입출력 스트림을 사용하여 네트워크 오버헤드 없이 빠른 통신을 제공합니다.
Streamable HTTP 전송: HTTP POST를 사용하여 클라이언트-서버 간 메시지를 전송하며, Server-Sent Events(SSE)를 통한 스트리밍 기능을 지원합니다.
이 방식은 원격 서버 통신에 적합하며, Bearer 토큰, API 키, 커스텀 헤더 등 표준 HTTP 인증 방식을 지원합니다.
MCP는 인증 토큰 획득을 위해 OAuth 사용을 권장합니다.

전송 계층은 통신 세부 사항을 추상화하여, 모든 전송 메커니즘에서 동일한 JSON-RPC 2.0 메시지 형식을 사용할 수 있게 합니다.

2-1-3. 데이터 계층 프로토콜 (Data Layer Protocol)

MCP의 핵심은 MCP 클라이언트와 MCP 서버 간의 스키마 및 의미 체계를 정의하는 것입니다.
개발자에게 가장 흥미로운 부분은 프리미티브(Primitives)로, MCP 서버에서 MCP 클라이언트로 컨텍스트를 공유하는 방법을 정의합니다. MCP는 기본 RPC 프로토콜로 JSON-RPC 2.0을 사용합니다. 클라이언트와 서버는 요청(request)과 응답(response)을 주고받으며, 응답이 필요 없는 경우 알림(notification)을 사용할 수 있습니다.

생명주기 관리 (Lifecycle Management)

MCP는 상태를 유지하는(stateful) 프로토콜로, 생명주기 관리가 필요합니다. 그 목적은 클라이언트와 서버가 지원하는 기능(capabilities)을 협상하는 것입니다. 자세한 내용은 명세서와 예시에서 확인할 수 있습니다.

프리미티브 (Primitives)

MCP의 프리미티브는 MCP의 가장 중요한 개념입니다. 이는 클라이언트와 서버가 서로에게 제공할 수 있는 기능을 정의하며, AI 애플리케이션과 공유할 수 있는 컨텍스트 정보의 유형과 수행 가능한 작업의 범위를 규정합니다.

서버가 노출할 수 있는 세 가지 핵심 프리미티브:

도구 (Tools): AI 애플리케이션이 호출할 수 있는 실행 가능한 함수 (예: 파일 작업, API 호출, 데이터베이스 쿼리)
리소스 (Resources): AI 애플리케이션에 컨텍스트 정보를 제공하는 데이터 소스 (예: 파일 내용, DB 레코드, API 응답)
프롬프트 (Prompts): 언어 모델과의 상호작용을 구조화하는 재사용 가능한 템플릿 (예: 시스템 프롬프트, few-shot 예시)

각 프리미티브 유형은 */list, */get, tools/call 등의 메서드를 통해 검색, 조회, 실행할 수 있습니다. 예를 들어, 클라이언트는 tools/list로 사용 가능한 도구를 나열한 후, 특정 도구를 실행할 수 있습니다.

예시:
데이터베이스 관련 MCP 서버는 다음을 제공할 수 있습니다:

쿼리 실행 도구
데이터베이스 스키마 리소스
쿼리 예시를 포함한 프롬프트

클라이언트가 노출할 수 있는 프리미티브:

샘플링 (Sampling): 서버가 클라이언트의 AI 애플리케이션에서 언어 모델 출력을 요청할 수 있게 합니다.
유도 (Elicitation): 서버가 사용자에게 추가 정보를 요청하거나 작업을 확인할 수 있게 합니다.
로깅 (Logging): 서버가 클라이언트로 로그 메시지를 전송할 수 있게 합니다.

유틸리티 프리미티브 (Utility Primitives):

작업 (Tasks, 실험적): 장기 실행 작업의 상태 추적 및 결과 조회를 지원하는 내구성 있는 실행 래퍼입니다.
(예: 복잡한 계산, 워크플로 자동화, 배치 처리 등)

알림 (Notifications)

MCP는 서버와 클라이언트 간의 실시간 업데이트를 위한 알림을 지원합니다. 예를 들어, 서버의 도구 목록이 변경되면 서버는 tools/list_changed 알림을 전송하여 클라이언트에게 이를 통보할 수 있습니다.이 알림은 JSON-RPC 2.0의 알림 메시지( 응답을 기대하지 않고)형식을 따르며 MCP 서버와 연결된 클라이언트들에게 실시간 업데이트를 보낼 수 있습니다.

2-1-4. 예시 (Example)

데이터 계층 (Data Layer)

이 섹션은 MCP 클라이언트-서버 상호작용의 단계별 예시를 제공합니다. 생명주기 관리, 도구 작업, 알림을 JSON-RPC 2.0 메시지를 통해 설명합니다.

1단계: 초기화 (생명주기 관리)

클라이언트는 initialize 요청을 보내 연결을 설정하고 지원 기능을 협상합니다. 서버는 이에 대한 응답으로 자신의 기능을 반환합니다. 이후 클라이언트는 notifications/initialized 알림을 보내 준비 완료를 알립니다.

이 과정에서 다음이 수행됩니다:

# 요청 초기화
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "elicitation": {}
    },
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

# 응답 초기화
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": true
      },
      "resources": {}
    },
    "serverInfo": {
      "name": "example-server",
      "version": "1.0.0"
    }
  }
}

초기화 교환의 이해

초기화 프로세스는 MCP의 수명 주기 관리에서 핵심적인 부분이며, 다음과 같은 여러 중요한 목적을 가지고 있습니다:

프로토콜 버전 협상(Protocol Version Negotiation): protocolVersion 필드(예: “2025-06-18”)는 클라이언트와 서버가 호환 가능한 프로토콜 버전을 사용하고 있음을 보장합니다. 이를 통해 서로 다른 버전 간의 통신 오류를 방지할 수 있습니다. 만약 호환 가능한 버전을 협상하지 못하면 연결은 종료되어야 합니다.
기능 탐색(Capability Discovery): capabilities 객체는 각 측이 지원하는 기능을 선언할 수 있게 합니다. 여기에는 처리할 수 있는 기본 요소(도구, 리소스, 프롬프트 등)와 알림(notification) 기능 지원 여부가 포함됩니다. 이를 통해 지원되지 않는 작업을 피하고 효율적인 통신이 가능합니다.
식별 정보 교환(Identity Exchange): clientInfo와 serverInfo 객체는 디버깅 및 호환성 확인을 위한 식별 및 버전 정보를 제공합니다.

이 예시에서의 기능 협상(capability negotiation)은 MCP 기본 요소(primitives)가 어떻게 선언되는지를 보여줍니다:

클라이언트 기능(Client Capabilities):
- "elicitation": {} — 클라이언트는 사용자 상호작용 요청을 처리할 수 있음을 선언합니다(즉, elicitation/create 메서드 호출을 받을 수 있음).
서버 기능(Server Capabilities):
- "tools": {"listChanged": true} — 서버는 tools 기본 요소를 지원하며, 도구 목록이 변경될 때 tools/list_changed 알림을 보낼 수 있습니다.
- "resources": {} — 서버는 또한 resources 기본 요소를 지원하며, resources/list 및 resources/read 메서드를 처리할 수 있습니다.

초기화가 성공적으로 완료되면, 클라이언트는 준비가 완료되었음을 알리기 위해 다음과 같은 알림을 보냅니다:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

AI 애플리케이션에서의 동작 방식

초기화 과정 동안, AI 애플리케이션의 MCP 클라이언트 매니저는 설정된 서버들과의 연결을 설정하고, 각 서버의 기능(capabilities)을 저장합니다. 이후 애플리케이션은 이 정보를 활용하여 어떤 서버가 특정 기능(도구, 리소스, 프롬프트 등)을 제공할 수 있는지, 그리고 실시간 업데이트를 지원하는지를 판단합니다.

# Pseudo Code
async with stdio_client(server_config) as (read, write):
    async with ClientSession(read, write) as session:
        init_response = await session.initialize()
        if init_response.capabilities.tools:
            app.register_mcp_server(session, supports_tools=True)
        app.set_server_ready(session)

2단계: 도구 검색 (프리미티브)

연결이 설정되면, 클라이언트는 tools/list 요청을 보내 서버가 제공하는 도구 목록을 가져옵니다. 이 요청은 MCP의 도구 검색 메커니즘의 핵심적인 부분으로, 클라이언트가 서버에서 사용 가능한 도구들을 실제로 사용하기 전에 어떤 도구들이 있는지 이해할 수 있도록 해줍니다.

# Tools List Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

# Tools List Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "calculator_arithmetic",
        "title": "Calculator",
        "description": "Perform mathematical calculations including basic arithmetic, trigonometric functions, and algebraic operations",
        "inputSchema": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', 'sin(30)', 'sqrt(16)')"
            }
          },
          "required": ["expression"]
        }
      },
      {
        "name": "weather_current",
        "title": "Weather Information",
        "description": "Get current weather information for any location worldwide",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name, address, or coordinates (latitude,longitude)"
            },
            "units": {
              "type": "string",
              "enum": ["metric", "imperial", "kelvin"],
              "description": "Temperature units to use in response",
              "default": "metric"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

도구 검색 요청 이해하기

tools/list 요청은 매우 간단하며, 어떤 매개변수도 포함하지 않습니다.

도구 검색 응답 이해하기

응답에는 각 사용 가능한 도구에 대한 포괄적인 메타데이터를 제공하는 tools 배열이 포함되어 있습니다. 이 배열 기반 구조는 서버가 여러 도구를 동시에 노출하면서도 서로 다른 기능 간의 명확한 경계를 유지할 수 있도록 합니다.

응답 내 각 도구 객체에는 다음과 같은 주요 필드가 포함됩니다:

name: 서버 네임스페이스 내에서 도구를 고유하게 식별하는 식별자입니다. 이는 도구 실행의 기본 키 역할을 하며, 명확한 명명 규칙을 따르는 것이 좋습니다. (예: 단순히 calculate가 아닌 calculator_arithmetic)
title: 사용자가 볼 수 있도록 클라이언트가 표시할 수 있는 사람이 읽기 쉬운 도구 이름입니다.
description: 도구가 수행하는 작업과 사용 시점을 자세히 설명합니다.
inputSchema: 예상되는 입력 매개변수를 정의하는 JSON 스키마로, 타입 검증을 가능하게 하고 필수 및 선택 매개변수에 대한 명확한 문서를 제공합니다.

AI 애플리케이션에서의 작동 방식

AI 애플리케이션은 연결된 모든 MCP 서버로부터 사용 가능한 도구를 가져와 이를 통합된 도구 레지스트리로 결합합니다. 이렇게 하면 언어 모델이 수행할 수 있는 작업을 이해하고, 대화 중에 자동으로 적절한 도구 호출을 생성할 수 있게 됩니다.

# Pseudo-code using MCP Python SDK patterns
available_tools = []
for session in app.mcp_server_sessions():
    tools_response = await session.list_tools()
    available_tools.extend(tools_response.tools)
conversation.register_available_tools(available_tools)

3단계: 도구 실행 (Tool Execution)

클라이언트는 tools/call 요청을 통해 도구를 실행할 수 있습니다. 이는 MCP의 primitives들이 실제로 어떻게 사용되는지를 보여줍니다. 사용 가능한 도구를 검색한 후, 클라이언트는 적절한 인자를 사용하여 해당 도구를 호출할 수 있습니다.

도구 실행 요청 이해하기

tools/call 요청은 클라이언트와 서버 간의 타입 안정성과 명확한 통신을 보장하는 구조화된 형식을 따릅니다. 여기서 중요한 점은 단순화된 이름이 아닌, 검색 응답에서 제공된 올바른 도구 이름(weather_current)을 사용한다는 것입니다.

# Tool Call Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": {
      "location": "San Francisco",
      "units": "imperial"
    }
  }
}

# Tool Call Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in San Francisco: 68°F, partly cloudy with light winds from the west at 8 mph. Humidity: 65%"
      }
    ]
  }
}

도구 실행의 주요 요소

요청 구조에는 다음과 같은 중요한 구성 요소들이 포함됩니다:

name: 검색 응답에서 제공된 도구 이름(weather_current)과 정확히 일치해야 합니다. 이를 통해 서버는 어떤 도구를 실행해야 하는지 올바르게 식별할 수 있습니다.
arguments: 도구의 inputSchema에 정의된 입력 매개변수를 포함합니다. 예를 들어:
- location: “San Francisco” (필수 매개변수)
- units: “imperial” (선택 매개변수, 지정하지 않으면 기본값은 “metric”)
JSON-RPC 구조: 요청-응답 간의 상관관계를 위해 고유한 ID를 사용하는 표준 JSON-RPC 2.0 형식을 따릅니다.

도구 실행 응답 이해하기

응답은 MCP의 유연한 콘텐츠 시스템을 보여줍니다:

content 배열: 도구 응답은 콘텐츠 객체의 배열을 반환하며, 텍스트, 이미지, 리소스 등 다양한 형식의 풍부한 응답을 지원합니다.
콘텐츠 유형(Content Types): 각 콘텐츠 객체에는 type 필드가 있습니다. 예를 들어 "type": "text"는 일반 텍스트 콘텐츠를 의미하지만, MCP는 다양한 사용 사례를 위한 여러 콘텐츠 유형을 지원합니다.
구조화된 출력(Structured Output): 응답은 AI 애플리케이션이 언어 모델 상호작용의 문맥으로 활용할 수 있는 실행 가능한 정보를 제공합니다.

이 실행 패턴을 통해 AI 애플리케이션은 서버 기능을 동적으로 호출하고, 언어 모델과의 대화에 통합할 수 있는 구조화된 응답을 받을 수 있습니다.

AI 애플리케이션에서의 작동 방식

언어 모델이 대화 중에 도구 사용을 결정하면, AI 애플리케이션은 해당 도구 호출을 가로채어 적절한 MCP 서버로 라우팅하고, 실행한 뒤 결과를 LLM에 다시 전달합니다. 이를 통해 LLM은 실시간 데이터에 접근하고 외부 세계에서 실제 작업을 수행할 수 있게 됩니다.

# Pseudo-code for AI application tool execution
async def handle_tool_call(conversation, tool_name, arguments):
    session = app.find_mcp_session_for_tool(tool_name)
    result = await session.call_tool(tool_name, arguments)
    conversation.add_tool_result(result.content)

4단계: 실시간 업데이트 (알림)

MCP는 서버가 명시적인 요청 없이도 클라이언트에게 변경 사항을 알릴 수 있는 실시간 알림 기능을 지원합니다. 이는 MCP 연결을 동기화하고 반응성을 유지하는 핵심 기능인 알림 시스템을 보여줍니다.

도구 목록 변경 알림 이해하기

서버의 사용 가능한 도구가 변경될 때—예를 들어 새로운 기능이 추가되거나, 기존 도구가 수정되거나, 일시적으로 사용할 수 없게 되는 경우—서버는 연결된 클라이언트에게 이를 사전에 알릴 수 있습니다.

# Request
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

MCP 알림의 주요 기능

응답 불필요: 알림에는 id 필드가 없습니다. 이는 JSON-RPC 2.0의 알림 규칙을 따르며, 응답이 기대되거나 전송되지 않음을 의미합니다.
기능 기반(Capability-Based): 이 알림은 초기화 시 도구 기능에서 "listChanged": true로 선언한 서버에서만 전송됩니다(1단계에서 설명된 것처럼).
이벤트 기반(Event-Driven): 서버는 내부 상태 변경에 따라 알림을 보낼 시점을 결정하므로, MCP 연결은 동적이고 반응적으로 유지됩니다.

클라이언트의 알림 응답

이 알림을 수신하면, 클라이언트는 일반적으로 업데이트된 도구 목록을 요청하여 반응합니다. 이를 통해 클라이언트는 사용 가능한 도구에 대한 최신 정보를 지속적으로 유지할 수 있습니다.

# Response
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/list"
}

알림이 중요한 이유

이 알림 시스템은 여러 가지 이유로 매우 중요합니다:

동적 환경(Dynamic Environments): 서버 상태, 외부 종속성, 또는 사용자 권한에 따라 도구가 추가되거나 제거될 수 있습니다.
효율성(Efficiency): 클라이언트가 변경 사항을 주기적으로 확인(polling)할 필요 없이, 업데이트가 발생할 때 즉시 알림을 받습니다.
일관성(Consistency): 클라이언트가 항상 서버의 사용 가능한 기능에 대한 정확한 정보를 유지하도록 보장합니다.
실시간 협업(Real-time Collaboration): 변화하는 상황에 적응할 수 있는 반응형 AI 애플리케이션을 가능하게 합니다.

이러한 알림 패턴은 도구뿐만 아니라 다른 MCP 기본 요소에도 확장되어, 클라이언트와 서버 간의 포괄적인 실시간 동기화를 지원합니다.

AI 애플리케이션에서의 작동 방식

AI 애플리케이션이 도구 변경 알림을 받으면, 즉시 도구 레지스트리를 새로 고치고 LLM의 사용 가능한 기능을 업데이트합니다. 이를 통해 진행 중인 대화가 항상 최신 도구 세트에 접근할 수 있으며, LLM은 새 기능이 추가될 때마다 동적으로 적응할 수 있습니다.

# Pseudo-code for AI application notification handling
async def handle_tools_changed_notification(session):
    tools_response = await session.list_tools()
    app.update_available_tools(session, tools_response.tools)
    if app.conversation.is_active():
        app.conversation.notify_llm_of_new_capabilities()

* 참고

What is the Model Context Protocol (MCP)? - Model Context Protocol

What is the Model Context Protocol (MCP)?

modelcontextprotocol.io

[LeetCode] 309. Best Time to Buy and Sell Stock with Cooldown

ssehuun — Thu, 27 Nov 2025 21:01:07 +0900

Description

You are given an array prices where prices[i] is the price of a given stock on the ith day.

Find the maximum profit you can achieve. You may complete as many transactions as you like (i.e., buy one and sell one share of the stock multiple times) with the following restrictions:

After you sell your stock, you cannot buy stock on the next day (i.e., cooldown one day).
Note: You may not engage in multiple transactions simultaneously (i.e., you must sell the stock before you buy again).

Example 1:
Input: prices = [1,2,3,0,2]
Output: 3
Explanation: transactions = [buy, sell, cooldown, buy, sell]

Example 2:
Input: prices = [1]
Output: 0

Constraints:

1 <= prices.length <= 5000
0 <= prices[i] <= 1000

Solution1

# 해답은 맞으나 Input이 길어질 경우 Runtime Error
# Time complextivity: O(2^n)
# Space O(n)
# 예외 케이스: [48,12,60,93,97,42,25,64,17,56,85,93,9,48,52,42,58,85,81,84,69,36,1,54,23,15,72,15,11,94]

class Solution:
    def findProfit(self, i, buy, arr):
        n = len(arr)

        # Base case
        if i >= n:
            return 0

        # If we can buy
        if buy:
            take = -arr[i] + self.findProfit(i + 1, 0, arr)
            skip = self.findProfit(i + 1, 1, arr)
            return max(take, skip)

        # If we can sell
        else:
            sell = arr[i] + self.findProfit(i + 2, 1, arr)
            skip = self.findProfit(i + 1, 0, arr)
            return max(sell, skip)

    def maxProfit(self, prices: List[int]) -> int:
        return self.findProfit(0, 1, prices)

Solution2

# Input: [48,12,60,93,97,42,25,64,17,56,85,93,9,48,52,42,58,85,81,84,69,36,1,54,23,15,72,15,11,94]
# Output: 428

class Solution:
    def findProfit(self, i, buy, arr, memo):
        n = len(arr)
        # Base case
        if i >= n:
            return 0
        # 이미 계산된 값이 있으면 반환
        if (i, buy) in memo:
            return memo[(i, buy)]
        # If we can buy
        if buy:
            take = -arr[i] + self.findProfit(i + 1, 0, arr, memo)
            skip = self.findProfit(i + 1, 1, arr, memo)
            memo[(i, buy)] = max(take, skip)
        # If we can sell
        else:
            sell = arr[i] + self.findProfit(i + 2, 1, arr, memo)
            skip = self.findProfit(i + 1, 0, arr, memo)
            memo[(i, buy)] = max(sell, skip)
        return memo[(i, buy)]

    def maxProfit(self, prices: list[int]) -> int:
        memo = {}
        return self.findProfit(0, 1, prices, memo)

Solution3

# Bottom-Up 방식
# memo를 딕셔너리로 선언 후, key 초기화 필요

class Solution:
    def maxProfit(self, prices: List[int]) -> int:
        n = len(prices)
        if n == 0:
            return 0
        memo = {}
        memo[(n, 0)] = 0
        memo[(n, 1)] = 0
        memo[(n+1, 0)] = 0
        memo[(n+1, 1)] = 0

        for i in range(n - 1, -1, -1):
            # When we can buy
            memo[(i, 1)] = max(-prices[i] + memo[(i+1, 0)], memo[(i+1, 1)])
            # When we can sell
            memo[(i, 0)] = max(prices[i] + memo[(i+2, 1)], memo[(i+1, 0)])
        return memo[(0, 1)]

Solution4

# Bottom-Up 방식
# dp 배열 사용

class Solution:
    def maxProfit(self, prices: List[int]) -> int:
        n = len(prices)
        dp = [[0 for _ in range(2)] for _ in range(n + 2)]

        for i in range(n - 1, -1, -1):
            # When we can buy
            dp[i][1] = max(-prices[i] + dp[i + 1][0], dp[i + 1][1])

            # When we can sell
            dp[i][0] = max(prices[i] + dp[i + 2][1], dp[i + 1][0])

        return dp[0][1]

[Algorithm] DP programming

ssehuun — Thu, 20 Nov 2025 11:43:52 +0900

1. 피보나치 수열을 재귀 함수로 구현

import sys
import time


def fibo_recur(x):
    if x <= 1:
        return x
    return fibo_recur(x-1)+fibo_recur(x-2)
    
 
 if __name__ == "__main__":
    print(f"start: {time.time()}")
    start = time.time()
    print(fibo_recur(40))
    end = time.time()
    print(f"end: {end}, total: {end - start:.6f}초")


#### 출력값 ####
start: 1763604540.6283398
102334155
end: 1763604565.0303335, total: 24.401973초

2. 피보나치 수열을 재귀 함수와 메모이제이션 기법 추가(Top-Down)

import sys
import time

sys.setrecursionlimit(10**8)

dp = [0] * 41

def fibo_memo(x):
    if dp[x] != 0:
        return dp[x]
    if x <= 1:
        dp[x] = x
    else:
        dp[x] = fibo_memo(x-1)+fibo_memo(x-2)
    return dp[x]

if __name__ == "__main__":
    print(f"start: {time.time()}")
    start = time.time()
    print(fibo_memo(40))
    end = time.time()
    print(f"end: {end}, total: {end - start:.6f}초")

#### 출력 ####
start: 1763604814.879065
102334155
end: 1763604814.8791049, total: 0.000021초

3. 피보나치 수열을 반복문으로 구현(Bottom-Up)

import sys
import time

sys.setrecursionlimit(10**8)

def fibo_iter(x):
    dp[0], dp[1] = 0, 1

    for i in range(2, x+1):
        dp[i] = dp[i-1]+dp[i-2]
    return dp[x]
    

if __name__ == "__main__":
    print(f"start: {time.time()}")
    start = time.time()
    print(fibo_iter(40))    
    end = time.time()
    print(f"end: {end}, total: {end - start:.6f}초")

#### 출력 ####
start: 1763605799.6194804
102334155
end: 1763605799.6195118, total: 0.000013초

[Leetcode] 419. Battleships in a Board

ssehuun — Tue, 18 Nov 2025 00:07:15 +0900

Description

Given an m x n matrix board where each cell is a battleship 'X' or empty '.', return the number of the battleships on board.

Battleships can only be placed horizontally or vertically on board. In other words, they can only be made of the shape 1 x k (1 row, k columns) or k x 1 (k rows, 1 column), where k can be of any size. At least one horizontal or vertical cell separates between two battleships (i.e., there are no adjacent battleships).

Example 1:

Input: board = [["X",".",".","X"],[".",".",".","X"],[".",".",".","X"]]
Output: 2

Example 2:

Input: board = [["."]]
Output: 0

Constraints:

m == board.length
n == board[i].length
1 <= m, n <= 200
board[i][j] is either '.' or 'X'.

Solution

from typing import List


nx = [1, 0, -1, 0]
ny = [0, 1, 0, -1]
global chk_mat, m, n

class Solution:
    def bfs(self, y, x, board):
        q = []
        q.append((x, y))
        
        while len(q) > 0:
            sx, sy = q.pop()
            # print("sx: ", sx, "sy: ", sy)
            chk_mat[sy][sx] = True

            if board[sy][sx] == ".":
                continue            

            for i in range(4):
                x = sx + nx[i]
                y = sy + ny[i]
                # print("new x: ", x, "new y: ", y)
                if x < 0 or y >= m or y < 0 or x >= n:
                    continue
                if chk_mat[y][x] == False:
                    chk_mat[y][x] = True
                    q.append((x, y))

    def countBattleships(self, board: List[List[str]]) -> int:
        global chk_mat, m, n
        m = len(board) # y축
        n = len(board[0]) # x축
        cnt = 0
        chk_mat = [[False] * n for _ in range(m)]
        # print("chk_mat: ", chk_mat)
        for y in range(m):
            for x in range(n):
                # print("y: ", y, "x: ", x)
                if board[y][x] == "." or chk_mat[y][x] == True:
                    continue
                if board[y][x] == "X":
                    self.bfs(y, x, board)
                    cnt += 1
        return cnt

출처

https://leetcode.com/problems/battleships-in-a-board/description/

[Python] uv 기본 사용법

ssehuun — Wed, 5 Nov 2025 17:20:33 +0900

uv 설치방법

linux 환경

# Linux/macOS curl 명령어
curl -LsSf https://astral.sh/uv/install.sh | sh

# Linux/macOS uv 특정 버전 설치
curl -LsSf https://astral.sh/uv/0.8.22/install.sh | sh

# Linux/macOS wget 명령어
wget -qO- https://astral.sh/uv/install.sh | sh

windows 환경

# Windows uv 최신 버전 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Windows uv 특정 버전 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.8.22/install.ps1 | iex"

pip & docker 설치

# pip 설치
pip install uv

# homebrew 설치
brew install uv

# docker 설치
docker pull ghcr.io/astral-sh/uv:0.8.22-python3.13-trixie-slim
참고 - https://docs.astral.sh/uv/guides/integration/docker/

uv 제거

# uv 데이터 삭제 (Optional)
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

# Linux/macOS
rm ~/.local/bin/uv ~/.local/bin/uvx

# Windows
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

uv 기본 사용법

uv 설치 버전 확인

uv --version

uv로 프로젝트 생성

uv init my_project

uv 가상환경 생성

uv venv
=> venv 이름으로 가상환경 폴더 생성

uv venv venv_fastmcp
=> venv_fastmcp 이름으로 가상환경 폴더 생성

uv 가상환경 활성화

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate  # Windows

uv 가상환경 비활성화

deactivate

uv 패키지 추가

uv add 패키지명

uv 패키지 제거

uv remove 패키지명

uv 프로젝트 실행

uv run main.py

uv Python 버전 관리

uv로 python 설치

# 로컬에 파이썬 버전의 latest 버전 설치하기
uv python install 3.10

# 가상환경에 파이썬 버전 설치하기
uv venv --python 3.14.0

설치된 파이썬 버전 리스트와 사용가능한 파이썬 버전 확인

uv python list

프로젝트에서 특정 파이썬 버전 설정

# 아래 명령어를 해야 .python-version 에 사용할 버전이 명시됨
# 그렇지 않으면 기존 시스템에서 사용하던 파이썬 버전을 사용함
uv python pin 3.13

참고

https://docs.astral.sh/uv/guides/projects/#running-commands

[Python] redis-py 설치 및 사용법

ssehuun — Tue, 14 Oct 2025 17:05:09 +0900

Redis는 dictionary 기반의 인메모리 오픈소스 데이터베이스다. 이 글에서 주로 설명하는 것은 파이썬 기반의 redis-py client 모듈을 설치해서 redis 사용방법을 알아볼 것이다.

먼저 아래 링크에서 Redis 서버를 설치가 전제되어 있어야 한다.

Redis 데이터베이스 서버 설치

각 운영 환경마다 설치하는 명령어는 아래 링크를 참고하면 된다.

1. 도커에 설치

https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/docker/

2. 리눅스 OS

https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/apt/

3. 맥 OS

https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/homebrew/

4. Window OS (도커 설치 필요, 도커 환경에 설치와 동일)

https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/homebrew/

1. Redis client 설치(v 6.4.0)

pip install redis

# C로 컴파일된 파서를 사용해 빠른 파싱으로 성능이 좋음
pip install redis[hiredis]

결론부터 말씀드리면, `hiredis`는 C언어로 작성된 고성능 파서(Parser)이고, `redis-py`의 기본 파서는 순수 Python으로 작성되었기 때문입니다.

  조금 더 자세히 설명해 드릴게요.

  1. 언어의 근본적인 차이: C (컴파일 언어) vs. Python (인터프리터 언어)

  Redis 클라이언트와 서버는 특정 프로토콜(RESP: REdis Serialization Protocol)을 통해 통신합니다. 클라이언트가 "GET mykey" 같은 명령을 보내면, Redis 서버는 "$3\r\nbar\r\n"와 같은 형식의 응답을 보냅니다.

  이 응답을 받아서 파이썬 객체(문자열, 리스트 등)로 변환하는 과정을 파싱(Parsing)이라고 합니다. hiredis는 바로 이 파싱 작업을 처리하는 라이브러리입니다.

   * hiredis (C 언어):
       * 컴파일 언어: 코드가 실행되기 전에 컴퓨터가 직접 이해할 수 있는 기계어 코드로 번역(컴파일)됩니다.
       * 빠른 실행: 중간 과정 없이 CPU에서 바로 실행되므로 매우 빠릅니다. 특히 반복적이고 낮은 수준의 작업(바이트 스트림 처리 등)에서 압도적인 성능을 보입니다.
       * 메모리 효율: 메모리를 직접 제어하여 오버헤드가 적습니다.

   * 기본 파서 (Python 언어):
       * 인터프리터 언어: 코드를 한 줄씩 읽어 들여 해석(인터프리팅)하면서 실행합니다.
       * 실행 오버헤드: 코드를 해석하는 과정 자체가 추가적인 CPU 작업을 요구하므로 C보다 느립니다.
       * 편의성: 개발이 쉽고 유연하지만, 성능 면에서는 손해를 봅니다.

  비유하자면, C로 작성된 hiredis는 원어민 통역사와 같습니다. 말을 듣는 즉시 바로 이해하고 전달할 수 있습니다. 반면, Python으로 작성된 기본 파서는 사전을 계속 찾아봐야 하는 번역가와 같습니다. 각 단어(데이터 조각)를 해석하는 데
  시간이 더 걸립니다.

  2. 성능 차이가 두드러지는 경우

  이러한 성능 차이는 다음과 같은 상황에서 특히 중요해집니다.

   1. 많은 수의 작은 응답을 처리할 때: 초당 수만 건의 간단한 GET/SET 요청을 처리한다면, 각 응답을 파싱하는 데 드는 작은 시간 차이가 누적되어 전체 처리량(Throughput)에 큰 영향을 미칩니다.
   2. 크고 복잡한 응답을 처리할 때: Redis에서 매우 큰 리스트(List)나 해시(Hash)를 한 번에 가져올 때, 파싱해야 할 데이터의 양이 많아집니다. 이 경우 C로 구현된 hiredis의 빠른 처리 속도가 큰 이점을 가집니다.

  3. redis-py와 hiredis의 관계

  redis-py 라이브러리는 이 점을 잘 알고 있어서, 사용자의 파이썬 환경에 `hiredis`가 설치되어 있으면 자동으로 `hiredis`를 파서로 사용합니다. 만약 설치되어 있지 않으면 순수 파이썬으로 구현된 기본 파서를 사용합니다.

  따라서 redis-py 사용자라면 코드 수정 없이 hiredis를 설치하는 것만으로 간단하게 성능 향상 효과를 누릴 수 있습니다.

# hiredis 설치 (이것만 추가하면 redis-py가 자동으로 사용)
pip install hiredis

2. Redis 서버에 연결 및 확인

import redis

r = redis.Redis(host='localhost', port=6379, decode_responses=True)

# 연결확인
r.ping() # True

저장 및 추출

r.set('foo', 'bar') # True
r.get('foo') # bar

3. 명령어

- hset(name, key=None, value=None, mapping=None, items=None)

- 설명: hash 이름에 키, 값을 세팅하고 딕셔너리 형태도 hash 이름에 맵핑할 수 있다. items 파라미터는 딕셔너리로 이루어진 리스트도 hash 이름에 맵핑할 수 있다.

- 리턴값: field가 새로 추가되는 정수값을 리턴

- 예제

res1 = r.hset("myhash", "field1", "Hello")
print(res1)
# >>> 1 (필드 field1이 1개 들어감)

res2 = r.hget("myhash", "field1")
print(res2)
# >>> Hello

res3 = r.hset("myhash", mapping={"field2": "Hi", "field3": "World"})
print(res3)
# >>> 2 (필드 field2, field3 2개 들어감)

res4 = r.hget("myhash", "field2")
print(res4)
# >>> Hi

res5 = r.hget("myhash", "field3")
print(res5)
# >>> World

res6 = r.hgetall("myhash")
print(res6)
# >>> { "field1": "Hello", "field2": "Hi", "field3": "World" }

- hget(name, key)

- 설명: hash 이름에 맵핑되어 있는 key값으로 value값을 가져옴

- 리턴값: hash 이름에 맵핑되어 있는 key값으로 value값 or None

- 예제

res7 = r.hset("myhash", "field1", "foo")
print(res7)
# >>> 1

res8 = r.hget("myhash", "field1")
print(res8)
# >>> foo

res9 = r.hget("myhash", "field2")
print(res9)
# >>> None

- hdel(name, *keys)

- 설명: hash 이름에 맵핑되어 있는 key를 통해 필드(key, value)를 삭제

- 리턴값: 정수값(hash 이름에 맵핑되어 있는 삭제 할 필드의 수)

- 예제

hdel1 = r.hset("myhash", "field1", "foo")
print(hdel1)
# >>> 1

hdel2 = r.hdel("myhash", "field1")
print(hdel2)
# >>> 1

hdel3 = r.hdel("myhash", "field2")
print(hdel3)
# >>> 0

- xadd(name, fields, id='*', maxlen=None, approximate=True, nomkstream=False, minid=None, limit=None, ref_policy=None)

- 설명: 스트림에 추가한다.

- 파라미터

name (Union[bytes, str, memoryview]) : 스트림 이름

fields (Dict[Union[bytes, bytearray, memoryview, str, int, float], Union[bytes, bytearray, memoryview, str, int, float]]) : 스트림에 삽입되는 field/value 쌍으로 이루어진 딕셔너리

id (Union[int, bytes, str, memoryview]) : 기록이 삽입될 위치(기본적으로 추가됨)

maxlen (Optional[int]) : 해당 사이즈를 넘는 멤버는 잘라냄

approximate (bool) : 실제 스트림 크기는 maxlen 크기보다 조금 클 수 있음

nomkstream (bool) : true로 설정하면 스트림 minid를 생성하지 않음

minid (Optional[Union[int, bytes, str, memoryview]]) : 조회할 스트림의 최소 id, maxlen과 함께 지정할 수 없음

limit (Optional[int]) : 가져올 최대 항목 수를 지정

ref_policy (Optional[Literal['KEEPREF', 'DELREF', 'ACKED']]) : 트리밍 시 컨슈머 그룹을 위한 참조 정책

KEEPREF (default): When trimming, preserves references in consumer groups’ PEL
DELREF: When trimming, removes all references from consumer groups’ PEL
ACKED: When trimming, only removes entries acknowledged by all consumer groups

- 리턴값: 스트림에 멤버가 들어갈 때, id값(자동 생성)

- 예제

# XADD 명령: mystream에 데이터 추가
id1 = r.xadd("mystream", {"name": "Sara", "surname": "OConnor"})
print("첫 번째 ID:", id1)
# 첫 번째 ID:1760422182743-0

id2 = r.xadd("mystream", {"field1": "value1", "field2": "value2", "field3": "value3"})
print("두 번째 ID:", id2)
# 두 번째 ID:1760422182743-1

# XLEN 명령: 스트림 길이 확인
length = r.xlen("mystream")
print("스트림 길이:", length)
# 스트림 길이:2

4. 명령어 성능 비교

SET VS HSET 비교

구분	SET	HSET
데이터 구조	단순 Key-Value	Key 안에 여러 Field-Value 쌍 (객체 구조)
값의 종류	문자열, 숫자 등 단일 값	여러 필드와 값으로 구성된 해시맵
주요 사용 목적	단일 정보 저장 (캐시, 세션 ID 등)	구조화된 객체 데이터 저장 (사용자 프로필, 상품 정보 등)
업데이트 방식	전체 값을 통째로 덮어써야 함	특정 필드만 개별적으로 수정 가능
관련 명령어	GET, INCR, DECR, MSET	HGET, HGETALL, HINCRBY, HMSET

SET을 사용하는 경우

하나의 정보만 저장하면 될 때
- 웹 페이지 전체 HTML 캐시: SET cache:page:home "<html>..."
- 사용자 세션 ID: SET session:xyz "user_id:100"
- 단순 카운터: INCR page:view_count (SET 기반 명령어)

HSET을 사용하는 경우: (대부분의 경우 더 좋은 선택)

객체나 구조화된 데이터를 표현할 때
- 사용자 정보: user:100 키 안에 name, email, age, last_login 필드 저장
- 상품 정보: product:50 키 안에 name, price, stock_quantity 필드 저장
데이터의 일부만 자주 변경해야 할 때
- HSET의 가장 큰 장점입니다. 예를 들어, 사용자 정보에서 last_login 필드만 업데이트하고 싶을 때, HSET user:100 last_login "2025-09-24" 명령어 하나로 끝낼 수 있습니다.
- 만약 SET으로 모든 사용자 정보를 JSON 문자열로 저장했다면(SET user:100 '{"name": "Alice", ...}') 이 값을 업데이트하기 위해 다음과 같은 비효율적인 과정을 거쳐야 합니다.
  - 1. GET으로 전체 JSON 문자열을 가져온다.
  - 2. 애플리케이션에서 JSON을 파싱한다.
  - 3. last_login 값을 변경한다.
  - 4. 다시 JSON 문자열로 변환한다.
  - 5. SET으로 전체 문자열을 다시 저장한다.

성능 및 메모리

메모리 효율성
- HSET은 적은 수의 필드를 가질 때 ziplist(최신 버전에서는 listpack)라는 특별한 방식으로 데이터를 압축하여 저장합니다. 따라서 여러 개의 SET 키를 만드는 것보다 하나의 `HSET` 키를 사용하는 것이 메모리를 훨씬 적게 사용합니다.
성능
- 위에서 설명했듯이, 객체의 일부만 수정할 때 HSET이 GET -> 수정 -> SET 과정보다 훨씬 빠르고 원자적(atomic)입니다.

=> ziplist와 listpack 비교

ziplist와 listpack은 Redis의 내부 동작과 성능을 이해하는 데 매우 중요한 개념입니다.
결론부터 말씀드리면, `listpack`은 `ziplist`의 치명적인 단점인 '연쇄 업데이트(Cascading Updates)' 문제를 해결하기 위해 등장한 새로운 데이터 구조입니다. 현재 최신 Redis 버전에서는 ziplist 대신 listpack을 기본으로 사용합니다.

둘의 공통점은 메모리 절약입니다. 작은 크기의 Hash, List, Zset(Sorted Set) 데이터를 저장할 때, 일반적인 해시테이블이나 링크드 리스트보다 훨씬 적은 메모리를 사용하기 위해 고안된 특별한 데이터 구조입니다.

1. ziplist란? (구형 방식)

  ziplist는 이름처럼 리스트와 비슷하지만, 실제로는 포인터를 사용하지 않고 하나의 연속된 메모리 블록에 모든 데이터를 압축해서 저장하는 구조입니다. 각 데이터 항목(entry)은 다음과 같은 정보를 가집니다.

   * previous_entry_length: 이전 항목의 길이를 저장. 이 값 덕분에 리스트의 끝에서부터 거꾸로 탐색하는 것이 가능합니다.
   * encoding: 현재 항목의 데이터 타입과 길이에 대한 정보.
   * content: 실제 데이터.

  ziplist의 치명적인 문제: 연쇄 업데이트 (Cascading Updates)
  ziplist의 가장 큰 문제는 중간에 있는 데이터가 변경될 때 발생합니다.

   1. ziplist 안에 여러 개의 작은 항목(A, B, C, D...)이 저장되어 있다고 가정해 봅시다.
   2. 항목 C는 자신의 데이터 바로 앞에 "이전 항목 B의 길이" 정보를 1바이트로 저장하고 있었습니다. (예: B의 길이가 60바이트라서 1바이트로 표현 가능)
   3. 그런데 항목 B의 데이터가 업데이트되어 길이가 300바이트로 늘어났습니다.
   4. 이제 항목 C는 "이전 항목 B의 길이"를 더 이상 1바이트로 표현할 수 없고, 5바이트(길이 정보 인코딩용 1바이트 + 길이 4바이트)로 늘려서 저장해야 합니다.
   5. 그 결과, 항목 C 자체의 전체 길이가 변경됩니다.
   6. 항목 C의 길이가 바뀌었으니, 다음 항목인 D에 저장된 "이전 항목 C의 길이" 정보도 변경되어야 합니다.
   7. 이런 식으로 하나의 항목 변경이 뒤따라오는 모든 항목의 길이 정보를 연쇄적으로 변경시키고, 최악의 경우 모든 데이터의 재할당 및 복사가 필요하게 됩니다.

  이 연쇄 업데이트는 시간 복잡도가 O(N²)에 달할 수 있어, Redis가 순간적으로 멈칫하는 지연 시간(Latency) 급증의 원인이 되었습니다.

  2. listpack이란? (신형 방식)

  listpack은 ziplist의 연쇄 업데이트 문제를 해결하기 위해 설계된 새로운 데이터 구조입니다. ziplist와 마찬가지로 하나의 연속된 메모리 블록을 사용하지만, 각 항목의 구조가 다릅니다.

   * encoding: 데이터 타입과 길이에 대한 정보.
   * content: 실제 데이터.
   * entry-length: 자기 자신의 전체 길이를 저장.

  listpack이 문제를 해결하는 방법
listpack의 핵심 아이디어는 "이전 항목의 길이"를 저장하지 않는 것입니다. 대신 "자기 자신의 길이"를 각 항목의 끝에 저장합니다.

   * 업데이트: 항목 B의 데이터가 변경되어도, 그 변경은 항목 B 내에서만 처리됩니다. 뒤따라오는 항목 C, D는 아무런 영향을 받지 않습니다. 연쇄 업데이트가 원천적으로 발생하지 않습니다.
   * 역방향 탐색: 리스트의 끝에서 이전 항목으로 이동하려면, 현재 항목의 끝에 저장된 "자기 자신의 길이" 정보를 읽고 그 길이만큼 메모리 포인터를 뒤로 이동하면 됩니다. ziplist보다 약간의 계산이 더 필요하지만, 연쇄 업데이트라는 큰 문제를 해결하는 대가로는 사소한 비용입니다.

3. 언제 압축된 구조를 사용하는가?

  Redis는 데이터가 특정 조건을 만족할 때만 ziplist나 listpack 같은 압축 구조를 사용합니다. 그 조건을 벗어나면 일반적인 데이터 구조(예: 해시테이블)로 자동 변환됩니다.

  이 조건은 redis.conf 설정 파일에서 제어하며, 아래 두 조건 중 하나라도 초과하면 압축이 해제됩니다.
   1. 항목의 개수: 해시나 리스트에 들어있는 필드 또는 요소의 개수
   2. 각 항목의 크기: 필드나 요소 중 가장 큰 값의 바이트 크기

  설정 예시 (`redis.conf`):

   * Hash 타입의 경우:
       * hash-max-listpack-entries 256 (기본값은 512였으나 최근 변경)
       * hash-max-listpack-value 64
       * => 해시의 필드 개수가 256개를 초과하거나, 필드 값 중 64바이트를 초과하는 것이 하나라도 있으면 일반 해시테이블로 변환됩니다.

   * List 타입의 경우:
       * list-max-listpack-entries 256
       * list-max-listpack-value 64
       * => 리스트의 요소 개수가 256개를 초과하거나, 요소 값 중 64바이트를 초과하는 것이 있으면 Quicklist 구조로 변환됩니다.

   * Zset(Sorted Set) 타입의 경우:
       * zset-max-listpack-entries 128
       * zset-max-listpack-value 64

  > 참고: 오래된 Redis 버전이나 설정 파일에서는 *-max-ziplist-* 라는 이름의 설정을 볼 수 있습니다. 원리는 동일합니다.

구분	ziplist	listpack
목표	작은 데이터 집합의 메모리 절약	작은 데이터 집합의 메모리 절약
구조	각 항목이 이전 항목의 길이를 저장	각 항목이 자기 자신의 길이를 저장
장점	뛰어난 메모리 효율성	뛰어난 메모리 효율성 + 안정적인 성능
단점	연쇄 업데이트로 인한 성능 저하 위험	역방향 탐색 시 약간의 추가 계산 필요
결론	Redis 7.0부터 사용 중단(deprecated)	현재 Redis의 표준 압축 방식

출처

redis 오픈소스 db설치 - https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/

파이썬 redis-py 6.4.0 - redis-py 6.4.0 documentation / https://redis.io/docs/latest/develop/clients/redis-py/

파이썬 모듈 - redis · PyPI

hiredis 모듈 - https://github.com/redis/hiredis

redis 문서 - https://redis.readthedocs.io/en/stable/commands.html#redis.commands.core.CoreCommands.hset

redis 공식문서 - https://redis.io/docs/latest/commands/hset/

[Python] async, sync, block, non-blocking 비교 및 사용방법

ssehuun — Wed, 17 Sep 2025 10:34:17 +0900

목차: 파이썬으로 이해하는 I/O 모델 (Sync, Async, Blocking, Non-blocking)

1. 시작하며: 개발자에게 I/O 모델이 왜 중요한가

1-1. 문제의 발견: 느린 I/O 작업

1-2. 핵심 비유: "유능한 셰프(CPU)와 게으른 웨이터(I/O)"

2. 관점의 분리: I/O를 이해하는 두 가지 축

2-1. 결과 처리의 관점: Sync vs Async

2-2. 제어권의 관점: Blocking vs Non-blocking

1. 시작하며: 개발자에게 I/O 모델이 왜 중요한가?

1-1. 문제의 발견: 느린 I/O 작업

잘못된 예

- 웹 요청, DB 조회, 파일 읽기 등 I/O 작업이 프로그램 전체를 멈추게 하는 현상

- Python 코드로 보는 문제 상황: requests와 for문을 이용한 순차적 API 호출 예시

import requests
import time

# 각 API가 1초씩 걸린다고 가정하기 위해, 1초 지연시키는 URL 사용
URLS = [
   "https://httpbin.org/delay/1",
   "https://httpbin.org/delay/1",
   "https://httpbin.org/delay/1",
]

def fetch_url(url: str):
   """
   하나의 URL에서 데이터를 가져오는 간단한 함수
   """
   print(f"요청 시작: {url}, 현재 시각: {time.time()}")
   response = requests.get(url)
   print(f"요청 완료: {url}, 상태 코드: {response.status_code}")
   return response.json()

def main():
   print("동기-블로킹 방식으로 API 호출을 시작합니다...")
   start_time = time.time()

   for url in URLS:
       fetch_url(url)

   end_time = time.time()
   print(f"\n총 소요 시간: {end_time - start_time:.2f}초")

if __name__ == "__main__":
   main()

동기-블로킹 방식으로 API 호출을 시작합니다...
요청 시작: https://httpbin.org/delay/1, 현재 시각: 1757920222.9375117
요청 완료: https://httpbin.org/delay/1, 상태 코드: 200
요청 시작: https://httpbin.org/delay/2, 현재 시각: 1757920225.2385561
요청 완료: https://httpbin.org/delay/2, 상태 코드: 200
요청 시작: https://httpbin.org/delay/3, 현재 시각: 1757920228.7930906
요청 완료: https://httpbin.org/delay/3, 상태 코드: 200

총 소요 시간: 9.77초

"이 코드의 가장 큰 문제점은 '기다림의 낭비' 입니다."

1. 하나의 요청이 모든 것을 멈춘다: requests.get(url)가 호출되면, 우리 프로그램은 해당 API 서버가 응답을 줄 때까지 아무것도 하지 않고 멈춰서 기다립니다.

2. CPU는 놀고 있다: 네트워크 응답을 기다리는 3초 동안, 우리 컴퓨터의 빠른 CPU는 사실상 아무 일도 하지 않고 그저 대기만 하고 있습니다. 이것은 엄청난 자원 낭비입니다.

3. 순차적 대기: 첫 번째 API 요청이 완전히 끝나야만 비로소 두 번째 API 요청을 시작할 수 있습니다. 그리고 두 번째 요청이 끝날 때까지 또 멈춰서 기다립니다.

"마치 식당에서 손님 3명의 주문을 받는데, 첫 번째 손님의 요리가 나올 때까지 두 번째, 세 번째 손님의 주문을 받지 않고 주방만 쳐다보며 기다리는 비효율적인 웨이터와 같습니다."

"그렇다면, 웨이터가 세 명의 주문을 한 번에 받고, 주방에서 요리가 완성되는 대로 바로바로 서빙하는 방식은 어떨까요? 훨씬 효율적이겠죠. 이것이 바로 비동기(Asynchronous) 프로그래밍이 해결하고자 하는 문제입니다."

1-2. 핵심 비유: "유능한 셰프(CPU)와 게으른 웨이터(I/O)"

CPU는 매우 빠르지만, I/O 작업의 응답을 기다리며 시간을 낭비하는 상황 비유
이 구조를 배우는 이유 => I/O를 효율적으로 처리하여 셰프(CPU)를 쉬지 않게 만들자

Q. Asynchronous 프로그래밍으로 해야하는건 알겠는데, Non-Blocking 과의 차이를 아시나요?

Q. Synchronous 프로그래밍은 알겠는데 Blocking 과의 차이는 아시나요?

2. 관점의 분리: I/O를 이해하는 두 가지 축

2-1. 결과 처리의 관점: Sync vs Async

- 정의: 작업 결과를 누가, 그리고 언제 확인하여 처리하는가?
- Sync: 호출자가 직접 작업 완료를 확인하고 결과를 가져옴 (결과와 흐름이 동기화됨)
- Async: 작업이 끝나면 호출된 쪽(커널/이벤트 루프)이 알려줌 (결과와 흐름이 비동기화됨)

2-2. 제어권의 관점: Blocking vs Non-blocking

- 정의: 함수 호출 후, 제어권(실행 흐름)이 즉시 호출자에게 돌아오는가?
- Blocking: 작업이 끝날 때까지 호출자가 '차단'됨

- Non-blocking: 작업 완료 여부와 상관없이 즉시 반환됨

1. Synchrounous, blocking execution

- 순차적인 흐름, 하나의 함수 호출이 끝난 후 다음 함수 호출 되는 구조

# 1. SYNCHRONOUS EXECUTION
print("\n1. SYNCHRONOUS EXECUTION")
print("-" * 30)

def sync_task(name, duration):
    """Synchronous task that blocks execution"""
    print(f"{print_time()} Starting {name}")
    time.sleep(duration)  # Simulates work - BLOCKS the thread
    print(f"{print_time()} Finished {name}")
    return f"Result from {name}"

def run_sync_tasks():
    """Run tasks synchronously - one after another"""
    start_time = time.time()
    
    # These run sequentially - each blocks until complete
    result1 = sync_task("Task 1", 2)
    result2 = sync_task("Task 2", 1)
    result3 = sync_task("Task 3", 1)
    
    total_time = time.time() - start_time
    print(f"Sync total time: {total_time:.2f} seconds")
    print(f"Results: {[result1, result2, result3]}")
    
async def main():
    """Main function to demonstrate all concepts"""
    print("SYNCHRONOUS EXECUTION:")
    run_sync_tasks()

1. SYNCHRONOUS EXECUTION
------------------------------
SYNCHRONOUS EXECUTION:
13:52:40.803 Starting Task 1
13:52:42.805 Finished Task 1
13:52:42.805 Starting Task 2
13:52:43.806 Finished Task 2
13:52:43.806 Starting Task 3
13:52:44.807 Finished Task 3
Sync total time: 4.00 seconds

2. Asynchrounous, Non-blocking execution

- Network 통신, DB조회 등의 I/O 작업시 CPU가 다른 일을 할 수 있는 구조

import asyncio
import time

# 2. ASYNCHRONOUS EXECUTION
print("\n\n2. ASYNCHRONOUS EXECUTION")
print("-" * 30)

def print_time():
    """Utility function to print current time with 1/10 second precision"""
    current_time = time.time()
    fractional_seconds = f"{current_time:.1f}".split(".")[1]
    formatted_time = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(current_time))
    return f"{formatted_time}.{fractional_seconds}"

async def async_task(name, duration):
    """Asynchronous task that doesn't block the event loop"""
    print(f"{print_time()} Starting {name}")
    await asyncio.sleep(duration)  # Non-blocking sleep
    print(f"{print_time()} Finished {name}")
    return f"Result from {name}"

async def run_async_tasks():
    """Run tasks asynchronously - concurrently"""
    start_time = time.time()
    
    # These run concurrently - no blocking
    tasks = [
        async_task("Async Task 1", 2),
        async_task("Async Task 2", 1),
        async_task("Async Task 3", 1)
    ]
    
    results = await asyncio.gather(*tasks)
    
    total_time = time.time() - start_time
    print(f"Async total time: {total_time:.2f} seconds")
    print(f"Results: {results}")

async def main():
    print("ASYNCHRONOUS EXECUTION:")
    await run_async_tasks()

2. ASYNCHRONOUS EXECUTION
------------------------------
2025-09-16 12:05:24.6 Starting Async Task 1
2025-09-16 12:05:24.6 Starting Async Task 2
2025-09-16 12:05:24.6 Starting Async Task 3
2025-09-16 12:05:25.6 Finished Async Task 2
2025-09-16 12:05:25.6 Finished Async Task 3
2025-09-16 12:05:26.6 Finished Async Task 1
Async total time: 2.00 seconds

3. Synchrounous, Non-blocking execution

- A 함수가 B 함수를 호출했을 때, B 함수는 제어권을 바로 돌려준다.

- A 함수는 B 함수의 결과값을 얻기 위해 주기적으로 호출한다.

- polling 구조에 주로 사

import time
import datetime

# 시간 출력을 위한 헬퍼 함수
def print_time():
   return datetime.datetime.now().strftime("%H:%M:%S.%f")[:-3]

# 1. 논블로킹 작업을 시뮬레이션하는 클래스
class NonBlockingIOTask:
    def __init__(self, name, duration):
        self._name = name
        self._duration = duration
        self._start_time = time.time()
        print(f"{print_time()} | {self._name}: 작업 시작 (총 {self._duration}초 소요 예정). 호출자는 차단되지 않음.")

    def poll(self) -> bool:
        """
        작업이 완료되었는지 확인하는 메소드.
        이 메소드 자체가 블로킹되지 않음.
        """
        return time.time() >= self._start_time + self._duration

    def get_result(self) -> str:
        """작업이 완료되었을 때만 결과를 반환"""
        if self.poll():
             return f"Result from {self._name}"
        return None

# 2. 메인 로직: 논블로킹 작업을 주기적으로 폴링(polling)
def run_sync_nonblocking():
    print("\nSYNCHRONOUS NON-BLOCKING 예제")
    print("-" * 40)

    start_time = time.time()

    # 논블로킹 작업 생성. 이 호출은 즉시 반환됨.
    task = NonBlockingIOTask("Sync-Nonblocking Task", 2)

    # 작업이 완료될 때까지 계속해서 물어봄 (Polling)
    while not task.poll():
        # 이 루프 안에서 다른 작업을 할 수 있음을 보여줌
        print(f"{print_time()} | 메인 루프: 작업 완료를 기다리는 중... (다른 작업 수행 가능)")
        time.sleep(0.5) # 너무 빠르게 계속 물어보면 CPU 낭비이므로 잠시 대기

    # 루프가 끝났다는 것은 작업이 완료되었다는 의미
    # 이제 동기적으로 결과를 가져옴
    result = task.get_result()

    print(f"{print_time()} | {task._name}: 작업 최종 완료됨!")

    total_time = time.time() - start_time
    print(f"\n총 소요 시간: {total_time:.2f}초")
    print(f"결과: {result}")


if __name__ == "__main__":
    run_sync_nonblocking()

 SYNCHRONOUS NON-BLOCKING 예제
----------------------------------------
10:30:00.123 | Sync-Nonblocking Task: 작업 시작 (총 2초 소요 예정). 호출자는 차단되지 않음.
10:30:00.123 | 메인 루프: 작업 완료를 기다리는 중... (다른 작업 수행 가능)
10:30:00.625 | 메인 루프: 작업 완료를 기다리는 중... (다른 작업 수행 가능)
10:30:01.128 | 메인 루프: 작업 완료를 기다리는 중... (다른 작업 수행 가능)
10:30:01.630 | 메인 루프: 작업 완료를 기다리는 중... (다른 작업 수행 가능)
10:30:02.133 | Sync-Nonblocking Task: 작업 최종 완료됨!

총 소요 시간: 2.01초

4. Asynchrounous, blocking execution

- time.sleep(2)가 실행되는 동안 observer_task는 단 한 번도 실행되지 못한다. 이벤트 루프가 time.sleep(2)으로 blocking 되기 떄문

- Sync, Blocking 코드와 성능상 다를게 거의 없어서 거의 사용하지 않음

import asyncio
import time
import datetime

def print_time():
    return datetime.datetime.now().strftime("%H:%M:%S.%f")[:-3]

async def observer_task():
    """이 작업은 실행될 기회를 얻지 못할 것입니다."""
    while True:
        print(f"{print_time()} | [이벤트 루프] 관찰자 실행 중...")
        await asyncio.sleep(0.5)

async def main():
    print("잘못된 비동기 코드 예제 (이벤트 루프가 멈춤)")
    print("-" * 40)
    start_time = time.time()

    # 관찰자 작업을 백그라운드에서 실행하도록 스케줄링
    asyncio.create_task(observer_task())

    print(f"{print_time()} | [메인 코루틴] 이제 블로킹 함수 time.sleep()을 호출합니다...")

    # 이 코드는 이벤트 루프가 도는 스레드 자체를 멈춥니다!
    time.sleep(2)

    print(f"{print_time()} | [메인 코루틴] 2초간의 블로킹이 끝났습니다.")

    total_time = time.time() - start_time
    print(f"\n총 소요 시간: {total_time:.2f}초")

if __name__ == "__main__":
   asyncio.run(main())

잘못된 비동기 코드 예제 (이벤트 루프가 멈춤)
----------------------------------------
11:00:00.100 | [메인 코루틴] 이제 블로킹 함수 time.sleep()을 호출합니다...
(2초 동안 아무것도 출력되지 않고 프로그램이 완전히 멈춤)
11:00:02.100 | [메인 코루틴] 2초간의 블로킹이 끝났습니다.

총 소요 시간: 2.00초

*** Asyncronous와 blocking 함수를 동시에 사용하고 싶다?

=> 왜냐면 많은 파이썬 패키지나 라이브러리가 sync 함수로 구현이 되어 있지 않음

=> 이벤트 루프에서 loop.run_in_executor()가 별도의 스레드를 생성 > 만들어 스레드 안에서 blocking 함수가 실행

import asyncio
import time
import datetime

def blocking_function(duration):
    """A function that blocks using time.sleep()."""
    print(f"{datetime.datetime.now().time()} - 블로킹 함수 시작 (실행 시간: {duration}초)")
    time.sleep(duration)
    print(f"{datetime.datetime.now().time()} - 블로킹 함수 종료")

async def main():
    start_time = time.time()
    print(f"{datetime.datetime.now().time()} - 메인 프로그램 시작")

    loop = asyncio.get_running_loop() # 현재 OS에서 실행중인 이벤트 루프 반환

    await asyncio.gather(
        # 블로킹 함수를 별도 스레드에서 실행
        loop.run_in_executor(None, blocking_function, 2),
        non_blocking_task("비동기 작업", 3)
    )

    end_time = time.time()
    print(f"{datetime.datetime.now().time()} - 메인 프로그램 종료")
    print(f"총 실행 시간: {end_time - start_time:.2f}초")

    async def non_blocking_task(task_name, duration):
    """A non-blocking task."""
        print(f"{datetime.datetime.now().time()} - {task_name}: 시작 (실행 시간: {duration}초)")
        await asyncio.sleep(duration)
        print(f"{datetime.datetime.now().time()} - {task_name}: 종료")

if __name__ == "__main__":
    asyncio.run(main())

09:21:42.936728 - 메인 프로그램 시작
09:21:42.938211 - 블로킹 함수 시작 (실행 시간: 2초)
09:21:42.938420 - 비동기 작업: 시작 (실행 시간: 3초)
09:21:44.940556 - 블로킹 함수 종료
09:21:45.940198 - 비동기 작업: 종료
09:21:45.940362 - 메인 프로그램 종료
총 실행 시간: 3.00초

실행 흐름

"blocking_function" (동기 작업)

main() 함수가 asyncio.gather()를 호출 (gather는 두 가지 작업을 동시에 시작시킴)
loop.run_in_executor를 통해 호출
이벤트 루프는 이 함수를 직접 실행하지 않고 스레드 풀의 워커 스레드(worker thread) 중 하나에게 위임

"non_blocking_task" (비동기 작업)

main() 함수가 asyncio.gather()를 호출 (gather는 두 가지 작업을 동시에 시작시킴)
이 작업은 메인 스레드의 이벤트 루프가 직접 관리
await syncio.sleep(3)을 만나면, 이벤트 루프는 이 작업을 잠시 멈추고 다른 일을 할 수 있음

구분	non_blocking_task	blocking_function
실행 주체	메인 스레드(이벤트 루프) 이벤트 루프를 막지 않음	별도 스레드(스레드 풀) 별도 스레드에서 실행되어 이벤트 루프를 막지 않음

loop.run_in_executor(None, ...)의 역할
- asyncio의 이벤트 루프는 기본적으로 하나의 메인 스레드에서 실행됩니다.

- 만약 이벤트 루프가 관리하는 작업(task) 중 하나라도 time.sleep()과 같은 동기(blocking) 함수를 직접 호출하면, 이벤트 루프 전체가 그 시간 동안 멈춰버립니다.
- loop.run_in_executor()는 이러한 문제를 해결하기 위해 사용됩니다. 이 함수는 시간이 오래 걸리거나 블로킹될 수 있는 동기 함수를 별도의 스레드(또는 프로세스)에서 실행하도록 지시합니다.
- 첫 번째 인자로 None을 주면, asyncio는 기본적으로 내장된 ThreadPoolExecutor(스레드 풀 실행기)를 사용합니다.

Documentor 프로젝트 시퀀스 다이어그램

구현 내용

- Main 스레드는 sync 방식으로 실행되고, Agent 가 동작하기 위한 스레드를 생성 후(Agent의 추가될 때마다), 그 안에서 Async 방식으로 worker_loop라는 이벤트 루프를 생성 후 Agent가 실행됨

문제점

- Agent가 새로 생길때마맏 스레드가 새로 생성되므로, Agent가 계속 많아질 때는 context-switching의 발생으로 성능 저하

- Async함수로 구현이 되어 있지만 스레드로 Agent마다 나뉘어져 있기 때문에 제대로된 코루틴을 활용하지 못함

보완해야할 점

- Agent가 생성때마다 스레드를 생성하는 것보다 코루틴 이벤트 루프에 넣어 코루틴을 활용하게 리팩토링 필요

참고

https://kiyeon.tistory.com/26

https://developer.ibm.com/articles/l-async/

파이썬 공식문서

https://docs.python.org/ko/3.13/library/asyncio-eventloop.html#asyncio.get_running_loop

https://docs.python.org/ko/3.13/library/asyncio-eventloop.html#asyncio.loop.run_in_executor

https://docs.python.org/ko/3.13/library/asyncio-task.html#asyncio.gather