프로세스 그룹

프로세스를 명명된 그룹에 참여시키고 클러스터 전체의 모든 멤버에게 브로드캐스트합니다. Erlang/OTP pg를 모델로 합니다: 그룹은 동적이고, 프로세스는 여러 그룹에 속할 수 있으며, 멤버십은 gossip을 통해 클러스터 전체에서 추적됩니다.

범위 엔트리 종류와 설정은 프로세스 그룹을 참조하세요. 더 넓은 클러스터링 모델은 클러스터 가이드를 참조하세요.

로딩

local pg = require("pg")

범위 열기

프로세스 그룹은 범위 — pg.scope 레지스트리 엔트리 — 안에 존재합니다. 범위를 열어 작업할 인스턴스를 가져옵니다:

local group, err = pg.open("app:pg")
if err then
    return nil, err
end

파라미터	타입	설명
`id`	string	범위 엔트리 ID (형식: `"namespace:name"`)

반환: pg.Instance, error

권한: 범위 id에 대한 pg.open

프로세스가 종료되면 인스턴스가 자동으로 해제됩니다; 더 일찍 해제하려면 release()를 호출하세요. 다른 모든 작업은 인스턴스의 메서드이며, :로 호출됩니다.

참여 및 탈퇴

local ok, err = group:join("workers")           -- 단일 그룹
local ok, err = group:join({"workers", "all"})  -- 배치
local ok, err = group:leave("workers")

파라미터	타입	설명
`group`	string \| string[]	그룹 이름, 또는 배치 작업을 위한 이름 목록

반환: boolean, error

프로세스는 동일한 그룹에 여러 번 참여할 수 있으며, 완전히 탈퇴하려면 같은 횟수만큼 탈퇴해야 합니다(다중 참여 시맨틱). leave는 배치에서 최선 노력 방식이며, 프로세스가 명명된 그룹 중 어느 것의 멤버도 아닌 경우에만 오류를 반환합니다.

권한: 각 그룹 이름에 대한 pg.join / pg.leave

멤버 목록 조회

local members, err = group:get_members("workers")        -- 모든 노드
local local_members, err = group:get_local_members("workers")  -- 이 노드만

파라미터	타입	설명
`group`	string	그룹 이름

반환: string[], error — PID 문자열 배열 (알 수 없는 그룹의 경우 빈 배열)

권한: 그룹 이름에 대한 pg.get_members / pg.get_local_members

그룹 목록 조회

local groups, err = group:which_groups()         -- 클러스터의 모든 그룹
local local_groups, err = group:which_local_groups()  -- 로컬 멤버가 있는 그룹

반환: string[], error — 현재 멤버가 하나 이상 있는 그룹 이름

권한: pg.which_groups / pg.which_local_groups

브로드캐스트

그룹의 모든 멤버에게 메시지를 전송합니다. 각 멤버는 호출 프로세스로부터 topic 아래에서 수신합니다 — process.listen(topic)으로 처리하세요.

local ok, err = group:broadcast("workers", "task", {id = 42})   -- 모든 노드
local ok, err = group:broadcast_local("workers", "task", {id = 42})  -- 이 노드만

파라미터	타입	설명
`group`	string	대상 그룹
`topic`	string	메시지 토픽
`...`	any	0개 이상의 페이로드 값

반환: boolean, error

권한: 그룹 이름에 대한 pg.broadcast / pg.broadcast_local

그룹 모니터링

monitor는 하나의 그룹에 대한 참여/탈퇴 이벤트를 구독하고 현재 멤버를 원자적으로 반환합니다 — 스냅샷과 구독 사이에서 멤버십 변경이 누락될 수 없습니다.

local sub, members, err = group:monitor("workers")
if err then
    return nil, err
end

for _, pid in ipairs(members) do
    -- 구독 시점의 현재 멤버
end

local ch = sub:channel()
local event = ch:receive()  -- {kind = "member.joined" | "member.left", path = "workers", data = {...}}

sub:close()  -- 구독 해제; sub:close({flush = true})는 먼저 대기 중인 이벤트를 소진

파라미터	타입	설명
`group`	string	감시할 그룹

반환: pg.Subscription, string[], error — 구독과 현재 멤버의 스냅샷

권한: 그룹 이름에 대한 pg.monitor

모든 그룹 감시

events는 범위의 모든 그룹에 걸쳐 멤버십 변경을 구독하고 모든 그룹의 멤버에 대한 스냅샷을 반환합니다.

local sub, snapshot, err = group:events()
-- snapshot: { ["workers"] = {pid, ...}, ["all"] = {pid, ...} }

local event = sub:channel():receive()
sub:close()

반환: pg.Subscription, table, error

권한: pg.events

이벤트 필드

구독 채널에서 전달되는 이벤트는 다음을 포함합니다:

필드	타입	설명
`system`	string	항상 `"pg"`
`kind`	string	`"member.joined"` 또는 `"member.left"`
`path`	string	그룹 이름
`data`	table	`{Group = string, PIDs = string[]}` — 영향받는 멤버

구독 채널은 버퍼링됩니다(용량 64); 느린 소비자가 버퍼를 가득 채우면 해당 구독에 대한 추가 이벤트는 삭제됩니다.

해제

group:release()

인스턴스를 즉시 해제합니다. 멱등합니다; 해제 후 모든 메서드는 오류를 반환합니다. 프로세스 종료 시 정리도 자동으로 실행됩니다.

반환: boolean

권한

권한	메서드	리소스
`pg.open`	`pg.open()`	범위 id
`pg.join`	`join()`	그룹 이름
`pg.leave`	`leave()`	그룹 이름
`pg.get_members`	`get_members()`	그룹 이름
`pg.get_local_members`	`get_local_members()`	그룹 이름
`pg.which_groups`	`which_groups()`	(범위)
`pg.which_local_groups`	`which_local_groups()`	(범위)
`pg.broadcast`	`broadcast()`	그룹 이름
`pg.broadcast_local`	`broadcast_local()`	그룹 이름
`pg.monitor`	`monitor()`	그룹 이름
`pg.events`	`events()`	(범위)

에러

조건	종류
권한 거부됨	`errors.PERMISSION_DENIED`
인수 누락 또는 빈 인수	`errors.INVALID`
범위 찾을 수 없음	`errors.NOT_FOUND`
멤버십 없는 그룹 탈퇴	`errors.INVALID`
인스턴스 해제됨	`errors.INVALID`

에러 처리는 에러 처리를 참조하세요.

참고

프로세스 그룹 - 범위 엔트리 종류와 설정
클러스터 - 멤버십과 클러스터링 모델
프로세스 관리 - 개별 프로세스 스폰 및 메시징