커뮤니케이터 API¶
커뮤니케이터를 만들고, 조회하고, 정리하는 함수입니다. 랭크들이 서로를 찾는 순서는 커뮤니케이터에서 설명합니다.
생성¶
LcclGetUniqueId¶
커뮤니케이터를 만드는 데 쓸 고유 ID를 만듭니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
out |
출력 | 고유 ID를 받을 포인터 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
커뮤니케이터마다 한 랭크에서 한 번만 호출하고, LcclCommInitRank()를 부르기 전에 같은 값을 모든 랭크에 전달하십시오. 배포 방법은 커뮤니케이터를 보십시오.
LcclCommInitRank¶
랭크 하나의 커뮤니케이터를 만듭니다. 랭크마다 스레드나 프로세스를 따로 두는 구성에 씁니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
newcomm |
출력 | 새 커뮤니케이터 핸들 |
nranks |
입력 | 커뮤니케이터의 랭크 수 |
comm_id |
입력 | 모든 랭크가 공유하는 고유 ID |
myrank |
입력 | 이 랭크의 번호 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
myrank는 0 이상nranks미만이고 같은 커뮤니케이터 안에서 유일해야 합니다.- 랭크마다 HyperAccel 디바이스 하나가 연결됩니다. 이 함수를 부르기 전에 호출 스레드에서 디바이스를 고르십시오.
- 이 함수는 다른 랭크가 모두 모일 때까지 기다립니다. 그래서 랭크마다 다른 스레드나 프로세스에서 부르거나, 한 스레드라면
LcclGroupStart()와LcclGroupEnd()로 감싸야 합니다.
LcclCommInitRankConfig¶
LcclCommInitRank()와 같지만 LcclConfig로 설정을 직접 지정합니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
newcomm |
출력 | 새 커뮤니케이터 핸들. 실패 여부는 반환값으로 확인하고, 실패한 호출의 newcomm은 쓰지 마십시오 |
nranks |
입력 | 커뮤니케이터의 랭크 수 |
comm_id |
입력 | 모든 랭크가 공유하는 고유 ID |
myrank |
입력 | 이 랭크의 번호 |
config |
입력 | 설정. 반드시 LCCL_CONFIG_INITIALIZER로 초기화해야 함 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
설정 항목과 값 검사는 커뮤니케이터를 보십시오.
LcclCommInitAll¶
한 프로세스 안에서 커뮤니케이터 묶음을 한 번에 만듭니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
출력 | 커뮤니케이터 ndev개를 받을 배열. ndev * sizeof(LcclComm) 이상으로 미리 할당 |
ndev |
입력 | 디바이스 수 |
devlist |
입력 | 디바이스 번호 목록 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
devlist는NULL일 수 없습니다.NULL이면kLcclCommNullPtr를 반환합니다. 중복 없는 유효한 디바이스 번호ndev개를 주십시오.devlist의 순서가 커뮤니케이터 안의 랭크 순서입니다.- 호출 전에 스레드에 디바이스를 바인딩해 두어야 합니다.
- 오류를 반환하면 그 프로세스에서는 LCCL을 더 쓰지 말고, 원인을 고친 뒤 새 프로세스에서 다시 시작하십시오.
- 이 함수는 모든 랭크의 장치 쪽 보조 자원을 호출 스레드에 바인딩된 카드 한 장에 할당합니다. 카드가 여러 장인 LPU에서 랭크의 자원이 각자의 카드에 놓여야 하면 랭크마다 스레드나 프로세스를 두고
LcclCommInitRank()를 쓰십시오.
조회¶
LcclCommCount¶
커뮤니케이터의 랭크 수를 돌려줍니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 조회할 커뮤니케이터 |
count |
출력 | 랭크 수 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
LcclCommUserRank¶
호출한 랭크가 커뮤니케이터 안에서 받은 번호를 돌려줍니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 조회할 커뮤니케이터 |
rank |
출력 | 랭크 번호 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
LcclCommHaDevice¶
커뮤니케이터가 구동하는 HyperAccel 디바이스 번호를 돌려줍니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 조회할 커뮤니케이터 |
device |
출력 | 디바이스 번호 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
LcclCommGetAsyncError¶
커뮤니케이터에 기록된 가장 최근의 비동기 오류를 읽습니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 조회할 커뮤니케이터 |
async_error |
출력 | 가장 최근의 비동기 오류 코드. 없으면 kLcclSuccess |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
논블로킹 커뮤니케이터의 진행 상태(kLcclInProgress)와, 전송 경로가 실패했을 때의 원인 코드를 읽는 데 씁니다. 한 번 기록된 오류는 지워지지 않습니다. 사용법은 에러 처리를 보십시오.
정리¶
LcclCommFinalize¶
남은 작업을 모두 마치고 커뮤니케이터를 정지합니다. 자원은 해제하지 않으므로 이어서 LcclCommDestroy()를 부릅니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 정지할 커뮤니케이터 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드. 같은 커뮤니케이터에 두 번 부르면 kLcclCommStateInvalid입니다.
LcclCommDestroy¶
커뮤니케이터에 딸린 로컬 자원을 해제합니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 해제할 커뮤니케이터 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
호출한 뒤 핸들은 쓸 수 없습니다. LcclCommAbort()와 둘 중 하나만 한 핸들에 한 번 부르십시오. 한 프로세스 안에 같은 커뮤니케이터에 속한 랭크가 여럿이면 그 랭크를 모두 정리해야 자원이 해제됩니다.
LcclCommAbort¶
커뮤니케이터의 진행 중인 작업을 모두 중단하고 자원을 회수합니다. 피어가 사라져 정상 종료가 끝나지 않을 때 씁니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 중단할 커뮤니케이터 |
반환 — 성공하면 kLcclSuccess, 아니면 오류 코드.
Note
호출한 뒤 핸들은 쓸 수 없고 LcclCommDestroy()를 다시 부르면 안 됩니다.
버퍼 등록¶
LcclCommRegister¶
네트워크 전송이 등록을 재사용할 수 있도록 장치 버퍼를 커뮤니케이터에 등록합니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 등록할 커뮤니케이터 |
buff |
입력 | 등록할 장치 버퍼 |
size |
입력 | 버퍼 크기(바이트). 0일 수 없음 |
handle |
출력 | LcclCommDeregister()에 넘길 등록 핸들 |
반환 — 성공하면 kLcclSuccess. 버퍼나 핸들이 null이거나 size가 0이면 kLcclCommInvalidArgs, 그 밖에는 오류 코드.
Note
- 이미 등록된 범위를 다시 등록하면 같은 핸들이 돌아옵니다. 성공한 호출마다
LcclCommDeregister()를 하나씩 짝지으십시오. - 등록은 네트워크 전송의
LcclSend/LcclRecv에서만 쓰이고, 상대 랭크의 맞은편 버퍼도 등록되어 있어야 합니다. 그렇지 않으면 불일치를 먼저 알아챈 랭크가 전송을 실패시키고 상대는LcclCommAbort()전까지 멈출 수 있습니다. - 네트워크 백엔드가 등록을 지원하지 않으면 호출은 성공하지만 버퍼는 등록되지 않은 것으로 다뤄집니다. 현재 번들된 백엔드(소켓, ibverbs)가 이에 해당합니다.
- 등록한 버퍼는 해제하기 전에
LcclCommDeregister()로 풀어 주십시오. 등록 중인 버퍼를HaMemFree하면 오류가 로그에 남고 그 등록이 풀립니다. 정리하지 않은 등록은LcclCommDestroy()와LcclCommAbort()에서 풀립니다. - 같은 커뮤니케이터의 집합 연산이나 그룹 호출과 동시에 부르지 마십시오.
LcclCommDeregister¶
LcclCommRegister()로 얻은 등록의 참조 하나를 풉니다.
1 | |
| 파라미터 | 방향 | 설명 |
|---|---|---|
comm |
입력 | 버퍼를 등록한 커뮤니케이터 |
handle |
입력 | LcclCommRegister()가 돌려준 핸들. null이어도 됨 |
반환
- 성공하거나 핸들이 null이면
kLcclSuccess - 핸들이 유효한 등록이 아니면
kLcclCommInvalidArgs - 같은 커뮤니케이터의 논블로킹 그룹이 아직 진행 중이면
kLcclCommStateInvalid - 커뮤니케이터에 이미 비동기 오류가 기록되어 있으면 그 오류. 마지막 두 경우에는 참조가 유지됩니다.
Note
마지막 참조가 풀릴 때만 실제 등록이 해제됩니다. null 핸들(LCCL_LOCAL_REGISTER=0일 때 LcclCommRegister()가 돌려줌)은 아무것도 하지 않습니다. 같은 커뮤니케이터의 집합 연산이나 그룹 호출과 동시에 부르지 마십시오.