C++ API¶
This reference is transcribed from the Doxygen comments in the public header lccl.h. The names are C-style, but the header is C++-only (default arguments, nullptr) and the hart headers it includes use C++17 features, so it must be compiled as C++17 or later.
1 | |
Build and link¶
lccl.h and libha_lccl.so are in the lccl/ directory of the site-packages where lccl is installed (lccl/include/lccl.h, lccl/libha_lccl.so). lccl.h includes the public headers of hart, and programs also call hart APIs such as HaSetDevice and HaMemAlloc, so give the hart package directory as well and link libha_runtime.so too. Put both directories in -rpath so the program finds both libraries when it runs. No CMake package files are provided.
1 2 3 4 5 6 7 8 | |
libha_lccl.so finds the other hart libraries it uses in hart/ of the same site-packages. If you keep hart in another directory, for example through PYTHONPATH, set LD_LIBRARY_PATH="$HART_DIR" when you run the program.
The LPU kernels are inside libha_lccl.so, so there are no kernel files to ship separately.
Sections¶
| Page | Contents |
|---|---|
| Communicator API | Unique ID, rank rendezvous, lifetime, queries, buffer registration |
| Collective Operations | all-reduce, reduce, reduce-scatter, broadcast, all-gather, gather, scatter, all-to-all |
| Point-to-Point API | Directional send and receive |
| Group API | Combining several operations into one launch |
| Types | Enumerations, aliases, structures, macros, string helpers |
How to read¶
This section covers what applies to all entry points and is not repeated on the individual pages.
- Every entry point except the type and string helpers (
LcclTypeSize,*ToString) returnsLcclResult. Output is passed through pointer parameters and can be written even when the call fails, so do not use the output of a failed call. - Buffers are device pointers. Obtain them from
hart; this library neither allocates nor validates them. countis the number of elements, not bytes.- An
HaStream_tparameter with a default value means the default stream of the calling thread. However,LcclAllGather,LcclAllToAll,LcclSend, andLcclRecvhave no stream argument at all, and a collective operation called outside a group has already completed when it returns but is not guaranteed to wait for stream work queued before the call. See Collective operations.
Topics that span several entry points, such as rank ordering, group semantics, and error classification, are not repeated here; they are explained once in the Programming guide.
Scope¶
The supported API is what lccl.h declares and this reference lists. The other headers in the source tree, including collectives.h and group.h, are internal and are not covered by compatibility guarantees, so do not include them directly.