콘텐츠로 이동

커뮤니케이터 API

커뮤니케이터를 만들고, 조회하고, 정리하는 함수입니다. 랭크들이 서로를 찾는 순서는 커뮤니케이터에서 설명합니다.


생성

LcclGetUniqueId

커뮤니케이터를 만드는 데 쓸 고유 ID를 만듭니다.

1
LcclResult LcclGetUniqueId(LcclUniqueId *out);
파라미터 방향 설명
out 출력 고유 ID를 받을 포인터

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

커뮤니케이터마다 한 랭크에서 한 번만 호출하고, LcclCommInitRank()를 부르기 전에 같은 값을 모든 랭크에 전달하십시오. 배포 방법은 커뮤니케이터를 보십시오.


LcclCommInitRank

랭크 하나의 커뮤니케이터를 만듭니다. 랭크마다 스레드나 프로세스를 따로 두는 구성에 씁니다.

1
LcclResult LcclCommInitRank(LcclComm *newcomm, int nranks, LcclUniqueId comm_id, int myrank);
파라미터 방향 설명
newcomm 출력 새 커뮤니케이터 핸들
nranks 입력 커뮤니케이터의 랭크 수
comm_id 입력 모든 랭크가 공유하는 고유 ID
myrank 입력 이 랭크의 번호

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

  • myrank는 0 이상 nranks 미만이고 같은 커뮤니케이터 안에서 유일해야 합니다.
  • 랭크마다 HyperAccel 디바이스 하나가 연결됩니다. 이 함수를 부르기 전에 호출 스레드에서 디바이스를 고르십시오.
  • 이 함수는 다른 랭크가 모두 모일 때까지 기다립니다. 그래서 랭크마다 다른 스레드나 프로세스에서 부르거나, 한 스레드라면 LcclGroupStart()와 LcclGroupEnd()로 감싸야 합니다.

LcclCommInitRankConfig

LcclCommInitRank()와 같지만 LcclConfig로 설정을 직접 지정합니다.

1
LcclResult LcclCommInitRankConfig(LcclComm *newcomm, int nranks, LcclUniqueId comm_id, int myrank, LcclConfig *config);
파라미터 방향 설명
newcomm 출력 새 커뮤니케이터 핸들. 실패 여부는 반환값으로 확인하고, 실패한 호출의 newcomm은 쓰지 마십시오
nranks 입력 커뮤니케이터의 랭크 수
comm_id 입력 모든 랭크가 공유하는 고유 ID
myrank 입력 이 랭크의 번호
config 입력 설정. 반드시 LCCL_CONFIG_INITIALIZER로 초기화해야 함

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

설정 항목과 값 검사는 커뮤니케이터를 보십시오.


LcclCommInitAll

한 프로세스 안에서 커뮤니케이터 묶음을 한 번에 만듭니다.

1
LcclResult LcclCommInitAll(LcclComm *comm, int ndev, const int *devlist);
파라미터 방향 설명
comm 출력 커뮤니케이터 ndev개를 받을 배열. ndev * sizeof(LcclComm) 이상으로 미리 할당
ndev 입력 디바이스 수
devlist 입력 디바이스 번호 목록

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

  • devlist는 NULL일 수 없습니다. NULL이면 kLcclCommNullPtr를 반환합니다. 중복 없는 유효한 디바이스 번호 ndev개를 주십시오. devlist의 순서가 커뮤니케이터 안의 랭크 순서입니다.
  • 호출 전에 스레드에 디바이스를 바인딩해 두어야 합니다.
  • 오류를 반환하면 그 프로세스에서는 LCCL을 더 쓰지 말고, 원인을 고친 뒤 새 프로세스에서 다시 시작하십시오.
  • 이 함수는 모든 랭크의 장치 쪽 보조 자원을 호출 스레드에 바인딩된 카드 한 장에 할당합니다. 카드가 여러 장인 LPU에서 랭크의 자원이 각자의 카드에 놓여야 하면 랭크마다 스레드나 프로세스를 두고 LcclCommInitRank()를 쓰십시오.

조회

LcclCommCount

커뮤니케이터의 랭크 수를 돌려줍니다.

1
LcclResult LcclCommCount(LcclComm comm, int *count);
파라미터 방향 설명
comm 입력 조회할 커뮤니케이터
count 출력 랭크 수

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.


LcclCommUserRank

호출한 랭크가 커뮤니케이터 안에서 받은 번호를 돌려줍니다.

1
LcclResult LcclCommUserRank(LcclComm comm, int *rank);
파라미터 방향 설명
comm 입력 조회할 커뮤니케이터
rank 출력 랭크 번호

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.


LcclCommHaDevice

커뮤니케이터가 구동하는 HyperAccel 디바이스 번호를 돌려줍니다.

1
LcclResult LcclCommHaDevice(LcclComm comm, int *device);
파라미터 방향 설명
comm 입력 조회할 커뮤니케이터
device 출력 디바이스 번호

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.


LcclCommGetAsyncError

커뮤니케이터에 기록된 가장 최근의 비동기 오류를 읽습니다.

1
LcclResult LcclCommGetAsyncError(LcclComm comm, LcclResult *async_error);
파라미터 방향 설명
comm 입력 조회할 커뮤니케이터
async_error 출력 가장 최근의 비동기 오류 코드. 없으면 kLcclSuccess

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

논블로킹 커뮤니케이터의 진행 상태(kLcclInProgress)와, 전송 경로가 실패했을 때의 원인 코드를 읽는 데 씁니다. 한 번 기록된 오류는 지워지지 않습니다. 사용법은 에러 처리를 보십시오.


정리

LcclCommFinalize

남은 작업을 모두 마치고 커뮤니케이터를 정지합니다. 자원은 해제하지 않으므로 이어서 LcclCommDestroy()를 부릅니다.

1
LcclResult LcclCommFinalize(LcclComm comm);
파라미터 방향 설명
comm 입력 정지할 커뮤니케이터

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드. 같은 커뮤니케이터에 두 번 부르면 kLcclCommStateInvalid입니다.


LcclCommDestroy

커뮤니케이터에 딸린 로컬 자원을 해제합니다.

1
LcclResult LcclCommDestroy(LcclComm comm);
파라미터 방향 설명
comm 입력 해제할 커뮤니케이터

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

호출한 뒤 핸들은 쓸 수 없습니다. LcclCommAbort()와 둘 중 하나만 한 핸들에 한 번 부르십시오. 한 프로세스 안에 같은 커뮤니케이터에 속한 랭크가 여럿이면 그 랭크를 모두 정리해야 자원이 해제됩니다.


LcclCommAbort

커뮤니케이터의 진행 중인 작업을 모두 중단하고 자원을 회수합니다. 피어가 사라져 정상 종료가 끝나지 않을 때 씁니다.

1
LcclResult LcclCommAbort(LcclComm comm);
파라미터 방향 설명
comm 입력 중단할 커뮤니케이터

반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.

Note

호출한 뒤 핸들은 쓸 수 없고 LcclCommDestroy()를 다시 부르면 안 됩니다.


버퍼 등록

LcclCommRegister

네트워크 전송이 등록을 재사용할 수 있도록 장치 버퍼를 커뮤니케이터에 등록합니다.

1
LcclResult LcclCommRegister(LcclComm comm, void *buff, size_t size, void **handle);
파라미터 방향 설명
comm 입력 등록할 커뮤니케이터
buff 입력 등록할 장치 버퍼
size 입력 버퍼 크기(바이트). 0일 수 없음
handle 출력 LcclCommDeregister()에 넘길 등록 핸들

반환 — 성공하면 kLcclSuccess. 버퍼나 핸들이 null이거나 size가 0이면 kLcclCommInvalidArgs, 그 밖에는 오류 코드.

Note

  • 이미 등록된 범위를 다시 등록하면 같은 핸들이 돌아옵니다. 성공한 호출마다 LcclCommDeregister()를 하나씩 짝지으십시오.
  • 등록은 네트워크 전송의 LcclSend/LcclRecv에서만 쓰이고, 상대 랭크의 맞은편 버퍼도 등록되어 있어야 합니다. 그렇지 않으면 불일치를 먼저 알아챈 랭크가 전송을 실패시키고 상대는 LcclCommAbort() 전까지 멈출 수 있습니다.
  • 네트워크 백엔드가 등록을 지원하지 않으면 호출은 성공하지만 버퍼는 등록되지 않은 것으로 다뤄집니다. 현재 번들된 백엔드(소켓, ibverbs)가 이에 해당합니다.
  • 등록한 버퍼는 해제하기 전에 LcclCommDeregister()로 풀어 주십시오. 등록 중인 버퍼를 HaMemFree하면 오류가 로그에 남고 그 등록이 풀립니다. 정리하지 않은 등록은 LcclCommDestroy()와 LcclCommAbort()에서 풀립니다.
  • 같은 커뮤니케이터의 집합 연산이나 그룹 호출과 동시에 부르지 마십시오.

LcclCommDeregister

LcclCommRegister()로 얻은 등록의 참조 하나를 풉니다.

1
LcclResult LcclCommDeregister(LcclComm comm, void *handle);
파라미터 방향 설명
comm 입력 버퍼를 등록한 커뮤니케이터
handle 입력 LcclCommRegister()가 돌려준 핸들. null이어도 됨

반환

  • 성공하거나 핸들이 null이면 kLcclSuccess
  • 핸들이 유효한 등록이 아니면 kLcclCommInvalidArgs
  • 같은 커뮤니케이터의 논블로킹 그룹이 아직 진행 중이면 kLcclCommStateInvalid
  • 커뮤니케이터에 이미 비동기 오류가 기록되어 있으면 그 오류. 마지막 두 경우에는 참조가 유지됩니다.

Note

마지막 참조가 풀릴 때만 실제 등록이 해제됩니다. null 핸들(LCCL_LOCAL_REGISTER=0일 때 LcclCommRegister()가 돌려줌)은 아무것도 하지 않습니다. 같은 커뮤니케이터의 집합 연산이나 그룹 호출과 동시에 부르지 마십시오.