cccl
CCCL 2.6.1
| คู่มือผู้สนับสนุน | ตู้คอนเทนเนอร์ | ความไม่ลงรอยกัน | Godbolt | โครงการ GitHub | เอกสาร |
|---|
ยินดีต้อนรับสู่ CUDA Core Compute Libraries (CCCL) ซึ่งภารกิจของเราคือการทำให้ Cuda มีความสุขมากขึ้น
ที่เก็บนี้รวมห้องสมุด CUDA C ++ ที่จำเป็นสามตัวลงในที่เก็บที่สะดวก:
เป้าหมายของ CCCL คือการจัดหา CUDA C ++ ให้กับนักพัฒนาด้วยการสร้างบล็อกที่ทำให้ง่ายต่อการเขียนโค้ดที่ปลอดภัยและมีประสิทธิภาพ การนำไลบรารีเหล่านี้มารวมกันทำให้กระบวนการพัฒนาของคุณเพิ่มความคล่องตัวและขยายความสามารถในการใช้ประโยชน์จากพลังของ CUDA C ++ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการตัดสินใจรวมโครงการเหล่านี้ดูประกาศที่นี่
แนวคิดสำหรับ CUDA Core Compute Libraries (CCCL) เติบโตขึ้นอย่างเป็นธรรมชาติจากโครงการ THRUST, CUB และ LIBCUDACXX ที่ได้รับการพัฒนาอย่างอิสระในช่วงหลายปีที่ผ่านมาโดยมีเป้าหมายที่คล้ายกัน: เพื่อให้การพัฒนา CUDA ที่มีคุณภาพสูงและใช้งานง่ายสำหรับนักพัฒนา CUDA โดยธรรมชาติมีการทับซ้อนกันมากมายในสามโครงการและเป็นที่ชัดเจนว่าชุมชนจะได้รับการบริการที่ดีขึ้นโดยรวมเข้ากับที่เก็บเดียว
THRUST เป็นไลบรารีอัลกอริทึมแบบขนาน C ++ ซึ่งเป็นแรงบันดาลใจในการเปิดตัวอัลกอริทึมแบบขนานไปยังไลบรารีมาตรฐาน C ++ อินเทอร์เฟซระดับสูงของ THRUST ช่วยเพิ่มประสิทธิภาพการทำงานของโปรแกรมเมอร์อย่างมากในขณะที่เปิดใช้งานการพกพาประสิทธิภาพระหว่าง GPU และซีพียูหลายตัวผ่านแบ็กเอนด์ที่กำหนดค่าได้ซึ่งอนุญาตให้ใช้เฟรมเวิร์กการเขียนโปรแกรมแบบขนานหลายเฟรม (เช่น CUDA, TBB และ OpenMP)
Cub เป็นไลบรารีเฉพาะระดับล่างที่ออกแบบมาสำหรับอัลกอริทึมแบบขนานความเร็วแสงในสถาปัตยกรรม GPU ทั้งหมด นอกเหนือจากอัลกอริทึมทั่วทั้งอุปกรณ์แล้วยังมี อัลกอริธึมแบบมีส่วนร่วม เช่นการลดทั่วทั้งบล็อกและการสแกนทั่วทั้ง Warp ทำให้นักพัฒนาเคอร์เนล CUDA มีการสร้างบล็อกเพื่อสร้างเมล็ดพันธุ์ที่กำหนดเอง
libcudacxx เป็นไลบรารีมาตรฐาน CUDA C ++ มันมีการใช้งานไลบรารีมาตรฐาน C ++ ที่ทำงานทั้งในโฮสต์และรหัสอุปกรณ์ นอกจากนี้ยังมี abstractions สำหรับคุณสมบัติฮาร์ดแวร์เฉพาะของ CUDA เช่นการซิงโครไนซ์ดั้งเดิมการควบคุมแคชอะตอมและอื่น ๆ
เป้าหมายหลักของ CCCL คือการเติมเต็มบทบาทที่คล้ายกันซึ่งห้องสมุด C ++ มาตรฐานเติมเต็มสำหรับมาตรฐาน C ++: จัดหาเครื่องมือความเร็วทั่วไปที่มีแสงสว่างให้กับนักพัฒนา CUDA C ++ ซึ่งช่วยให้พวกเขามุ่งเน้นไปที่การแก้ปัญหาที่สำคัญ การรวมโครงการเหล่านี้เป็นขั้นตอนแรกในการตระหนักถึงเป้าหมายนั้น
นี่เป็นตัวอย่างง่ายๆที่แสดงให้เห็นถึงการใช้ฟังก์ชั่น CCCL จากแรงขับ, Cub, และ libcudacxx
มันแสดงวิธีการใช้ THRUST/CUB/LIBCUDACXX เพื่อใช้เคอร์เนลการลดแบบขนานอย่างง่าย แต่ละบล็อกเธรดคำนวณผลรวมของชุดย่อยของอาร์เรย์โดยใช้ cub::BlockReduce ผลรวมของแต่ละบล็อกจะลดลงเป็นค่าเดียวโดยใช้ Adtomic Add ผ่าน cuda::atomic_ref จาก libcudacxx
จากนั้นจะแสดงให้เห็นว่าการลดลงแบบเดียวกันสามารถทำได้โดยใช้อัลกอริทึม reduce ผลักดันและเปรียบเทียบผลลัพธ์
ลองใช้ชีวิตบน Godbolt!
# include < thrust/execution_policy.h >
# include < thrust/device_vector.h >
# include < cub/block/block_reduce.cuh >
# include < cuda/atomic >
# include < cuda/cmath >
# include < cuda/std/span >
# include < cstdio >
template < int block_size>
__global__ void reduce (cuda::std::span< int const > data, cuda::std::span< int > result) {
using BlockReduce = cub::BlockReduce< int , block_size>;
__shared__ typename BlockReduce::TempStorage temp_storage;
int const index = threadIdx. x + blockIdx. x * blockDim. x ;
int sum = 0 ;
if ( index < data. size ()) {
sum += data[ index ];
}
sum = BlockReduce (temp_storage). Sum (sum);
if (threadIdx. x == 0 ) {
cuda::atomic_ref< int , cuda::thread_scope_device> atomic_result (result. front ());
atomic_result. fetch_add (sum, cuda::memory_order_relaxed);
}
}
int main () {
// Allocate and initialize input data
int const N = 1000 ;
thrust::device_vector< int > data (N);
thrust::fill (data. begin (), data. end (), 1 );
// Allocate output data
thrust::device_vector< int > kernel_result ( 1 );
// Compute the sum reduction of `data` using a custom kernel
constexpr int block_size = 256 ;
int const num_blocks = cuda::ceil_div (N, block_size);
reduce<block_size><<<num_blocks, block_size>>>(cuda::std::span< int const >( thrust::raw_pointer_cast (data. data ()), data. size ()),
cuda::std::span< int >( thrust::raw_pointer_cast (kernel_result. data ()), 1 ));
auto const err = cudaDeviceSynchronize ();
if (err != cudaSuccess) {
std::cout << " Error: " << cudaGetErrorString (err) << std::endl;
return - 1 ;
}
int const custom_result = kernel_result[ 0 ];
// Compute the same sum reduction using Thrust
int const thrust_result = thrust::reduce (thrust::device, data. begin (), data. end (), 0 );
// Ensure the two solutions are identical
std::printf ( " Custom kernel sum: %d n " , custom_result);
std::printf ( " Thrust reduce sum: %d n " , thrust_result);
assert (kernel_result[ 0 ] == thrust_result);
return 0 ;
}ทุกอย่างใน CCCL เป็นส่วนหัวเท่านั้น ดังนั้นผู้ใช้จำเป็นต้องกังวลเพียงว่าพวกเขาได้รับไฟล์ส่วนหัวและวิธีที่พวกเขารวมเข้ากับระบบบิลด์ของพวกเขา
วิธีที่ง่ายที่สุดในการเริ่มต้นใช้ CCCL คือผ่านชุดเครื่องมือ CUDA ซึ่งรวมถึงส่วนหัว CCCL เมื่อคุณรวบรวมด้วย nvcc จะเพิ่มส่วนหัว CCCL ลงในเส้นทางรวมของคุณโดยอัตโนมัติเพื่อให้คุณสามารถ #include หัว CCCL ใด ๆ ในรหัสของคุณโดยไม่ต้องกำหนดค่าเพิ่มเติม
หากรวบรวมกับคอมไพเลอร์อื่นคุณจะต้องอัปเดตระบบการสร้างของคุณรวมถึงเส้นทางการค้นหาเพื่อชี้ไปที่ส่วนหัว CCCL ในการติดตั้ง CTK ของคุณ (เช่น /usr/local/cuda/include )
# include < thrust/device_vector.h >
# include < cub/cub.cuh >
# include < cuda/std/atomic > ผู้ใช้ที่ต้องการอยู่บนขอบที่ทันสมัยของการพัฒนา CCCL ได้รับการสนับสนุนให้ใช้ CCCL จาก GitHub การใช้ CCCL รุ่นใหม่ที่มีรุ่นเก่าของ CUDA Toolkit รองรับ แต่ไม่ใช่วิธีอื่น ๆ สำหรับข้อมูลที่สมบูรณ์เกี่ยวกับความเข้ากันได้ระหว่าง CCCL และ CUDA Toolkit โปรดดูการสนับสนุนแพลตฟอร์มของเรา
ทุกอย่างใน CCCL เป็นส่วนหัวเท่านั้นดังนั้นการโคลนนิ่งและการรวมไว้ในโครงการที่เรียบง่ายนั้นง่ายเหมือนต่อไปนี้:
git clone https://github.com/NVIDIA/cccl.git
nvcc -Icccl/thrust -Icccl/libcudacxx/include -Icccl/cub main.cu -o mainหมายเหตุ ใช้
-Iและไม่ใช่-isystemเพื่อหลีกเลี่ยงการชนกับส่วนหัว CCCL รวมโดยnvccโดยปริยายจากชุดเครื่องมือ CUDA ส่วนหัวของ CCCL ทั้งหมดใช้#pragma system_headerเพื่อให้แน่ใจว่าคำเตือนจะยังคงเงียบราวกับว่าใช้-isystemดู #527 สำหรับข้อมูลเพิ่มเติม
บิลด์น้อยที่สุดที่สร้างกฎการติดตั้งเท่านั้นที่สามารถกำหนดค่าได้โดยใช้ install CMake ที่ตั้งไว้ล่วงหน้า:
git clone https://github.com/NVIDIA/cccl.git
cd cccl
cmake --preset install -DCMAKE_INSTALL_PREFIX=/usr/local/
cd build/install
ninja install ในการรวมไลบรารีทดลองในการติดตั้งให้ใช้การติดตั้งที่ install-unstable และไดเรกทอรี Build
ในการติดตั้ง เฉพาะ ไลบรารีทดลองให้ใช้ไดเรกทอรี install-unstable-only และสร้างไดเรกทอรี
CCCL ยังมีแพ็คเกจ conda ของแต่ละรีลีสผ่านช่องทาง conda-forge :
conda config --add channels conda-forge
conda install cccl สิ่งนี้จะติดตั้ง CCCL ล่าสุดไปยัง $CONDA_PREFIX/include/ และและ $CONDA_PREFIX/lib/cmake/ ไดเรกทอรี มันสามารถค้นพบได้โดย cmake ผ่าน find_package(CCCL) และสามารถใช้งานได้โดยคอมไพเลอร์ใด ๆ ในสภาพแวดล้อม conda สำหรับข้อมูลเพิ่มเติมโปรดดูบทนำเกี่ยวกับ Conda-Forge นี้
หากคุณต้องการใช้ CCCL เวอร์ชันเดียวกันที่ส่งมอบชุดเครื่องมือ CUDA โดยเฉพาะเช่น CUDA 12.4 คุณสามารถติดตั้ง CCCL ได้ด้วย:
conda config --add channels conda-forge
conda install cuda-cccl cuda-version=12.4 Metapackage cuda-cccl ติดตั้ง cccl เวอร์ชันที่ส่งมอบชุดเครื่องมือ CUDA ที่สอดคล้องกับ cuda-version หากคุณต้องการอัปเดตเป็น cccl ล่าสุดหลังจากติดตั้ง cuda-cccl ให้ถอนการติดตั้ง cuda-cccl ก่อนที่จะอัปเดต cccl :
conda uninstall cuda-cccl
conda install -c conda-forge ccclหมายเหตุ นอกจากนี้ยังมีแพ็คเกจ conda ที่มีชื่อเช่น
cuda-cccl_linux-64แพ็คเกจเหล่านั้นมีรุ่น CCCL ที่จัดส่งเป็นส่วนหนึ่งของชุดเครื่องมือ CUDA แต่ได้รับการออกแบบมาสำหรับการใช้งานภายในโดย CUDA Toolkit ติดตั้งccclหรือcuda-ccclแทนเพื่อเข้ากันได้กับคอมไพเลอร์ Conda สำหรับข้อมูลเพิ่มเติมดูสูตร CCCL Conda-Forge
CCCL ใช้ CMAKE สำหรับโครงสร้างพื้นฐานการสร้างและการติดตั้งทั้งหมดรวมถึงการทดสอบรวมถึงเป้าหมายในการเชื่อมโยงกับในโครงการ CMAKE อื่น ๆ ดังนั้น CMAKE จึงเป็นวิธีที่แนะนำในการรวม CCCL เข้ากับโครงการอื่น
สำหรับตัวอย่างที่สมบูรณ์ของวิธีการทำสิ่งนี้โดยใช้ CMake Package Manager ดูโครงการตัวอย่างพื้นฐานของเรา
ระบบการสร้างอื่น ๆ ควรใช้งานได้ แต่มีการทดสอบเฉพาะ CMake เท่านั้น การมีส่วนร่วมเพื่อลดความซับซ้อนของการรวม CCCL เข้ากับระบบบิลด์อื่น ๆ ยินดีต้อนรับ
สนใจที่จะมีส่วนร่วมในการทำให้ CCCL ดีขึ้นหรือไม่? ตรวจสอบคู่มือการสนับสนุนของเราสำหรับภาพรวมที่ครอบคลุมของทุกสิ่งที่คุณจำเป็นต้องรู้เพื่อตั้งค่าสภาพแวดล้อมการพัฒนาของคุณทำการเปลี่ยนแปลงเรียกใช้การทดสอบและส่ง PR
วัตถุประสงค์: ส่วนนี้อธิบายว่าผู้ใช้สามารถคาดหวังว่า CCCL จะรวบรวมและทำงานได้สำเร็จ
โดยทั่วไป CCCL ควรทำงานทุกที่ที่ CUDA Toolkit ได้รับการสนับสนุนอย่างไรก็ตามปีศาจอยู่ในรายละเอียด ส่วนด้านล่างอธิบายรายละเอียดของการสนับสนุนและการทดสอบสำหรับชุดเครื่องมือ CUDA รุ่นต่าง ๆ คอมไพเลอร์โฮสต์และภาษา C ++
สรุป:
ผู้ใช้ CCCL ได้รับการสนับสนุนให้ใช้ประโยชน์จากการปรับปรุงล่าสุดและ "Live at Head" โดยใช้ CCCL เวอร์ชันใหม่ล่าสุดเสมอ สำหรับประสบการณ์ที่ไร้รอยต่อคุณสามารถอัพเกรด CCCL ได้อย่างอิสระจากชุดเครื่องมือ CUDA ทั้งหมด สิ่งนี้เป็นไปได้เนื่องจาก CCCL รักษาความเข้ากันได้ย้อนหลังด้วยการเปิดตัวแพตช์ล่าสุดของรุ่น CTK เล็กน้อยทุกรุ่นจากทั้งซีรี่ส์รุ่นปัจจุบันและรุ่นก่อนหน้า ในบางกรณีพิเศษการเปิดตัว CUDA Toolkit รุ่นเล็กขั้นต่ำที่รองรับอาจต้องใหม่กว่ารุ่นที่เก่าแก่ที่สุดภายในซีรี่ส์รุ่นใหญ่ ตัวอย่างเช่น CCCL ต้องใช้เวอร์ชันที่รองรับขั้นต่ำ 11.1 จากซีรี่ส์ 11.x เนื่องจากปัญหาคอมไพเลอร์ที่หลีกเลี่ยงไม่ได้ที่อยู่ใน CTK 11.0
เมื่อมีการเปิดตัว CTK หลักใหม่เราจะได้รับการสนับสนุนสำหรับรุ่นสำคัญที่เก่าแก่ที่สุดที่รองรับ
| CCCL เวอร์ชัน | รองรับเวอร์ชัน CUDA Toolkit |
|---|---|
| 2.x | 11.1 - 11.8, 12.x (เฉพาะแพตช์ล่าสุดเท่านั้น) |
| 3.x (อนาคต) | 12.x, 13.x (เฉพาะแพตช์ล่าสุดเท่านั้น) |
รหัสที่ประพฤติตัวดีโดยใช้ CCCL ล่าสุดควรรวบรวมและทำงานได้สำเร็จด้วยรุ่น CTK ที่รองรับ ข้อยกเว้นอาจเกิดขึ้นสำหรับคุณสมบัติใหม่ที่ขึ้นอยู่กับคุณสมบัติ CTK ใหม่ดังนั้นคุณสมบัติเหล่านั้นจะไม่ทำงานกับ CTK รุ่นเก่า ตัวอย่างเช่นการสนับสนุน C ++ 20 ไม่ได้ถูกเพิ่มใน nvcc จนกระทั่ง CUDA 12.0 ดังนั้นคุณสมบัติ CCCL ที่ขึ้นอยู่กับ C ++ 20 จะไม่ทำงานกับ CTK 11.x
ผู้ใช้สามารถรวม CCCL รุ่นใหม่เข้ากับ CTK รุ่นเก่า แต่ไม่ใช่วิธีอื่น ๆ ซึ่งหมายความว่า CCCL รุ่นเก่านั้นไม่สามารถใช้งานได้กับ CTK รุ่นใหม่ กล่าวอีกนัยหนึ่ง CCCL ไม่เคยเข้ากันได้กับชุดเครื่องมือ CUDA
ตารางด้านล่างสรุปความเข้ากันได้ของ CTK และ CCCL:
| CTK เวอร์ชัน | รวม CCCL เวอร์ชัน | CCCL ที่ต้องการ | รองรับ? | หมายเหตุ |
|---|---|---|---|---|
ctk XY | CCCL MAJOR.MINOR | CCCL MAJOR.MINOR+n | คุณสมบัติใหม่บางอย่างอาจไม่ทำงาน | |
ctk XY | CCCL MAJOR.MINOR | CCCL MAJOR+1.MINOR | การหยุดพักที่เป็นไปได้; คุณสมบัติใหม่บางอย่างอาจไม่สามารถใช้ได้ | |
ctk XY | CCCL MAJOR.MINOR | CCCL MAJOR+2.MINOR | CCCL รองรับเพียงสองรุ่น CTK ที่สำคัญ | |
ctk XY | CCCL MAJOR.MINOR | CCCL MAJOR.MINOR-n | CCCL ไม่เข้ากันได้ | |
ctk XY | CCCL MAJOR.MINOR | CCCL MAJOR-n.MINOR | CCCL ไม่เข้ากันได้ |
สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดเวอร์ชัน CCCL ความเข้ากันได้ของ API/ABI และการเปลี่ยนแปลงที่แตกหักดูส่วนการกำหนดเวอร์ชันด้านล่าง
เว้นแต่จะระบุไว้เป็นอย่างอื่น CCCL รองรับระบบปฏิบัติการเดียวกันทั้งหมดเช่น CUDA Toolkit ซึ่งมีการบันทึกไว้ที่นี่:
เว้นแต่จะระบุไว้เป็นอย่างอื่น CCCL รองรับคอมไพเลอร์โฮสต์เดียวกันกับ CUDA Toolkit ล่าสุดซึ่งมีการบันทึกไว้ที่นี่:
เมื่อใช้ชุดเครื่องมือ CUDA รุ่นเก่าเรายังรองรับคอมไพเลอร์โฮสต์ของ CUDA Toolkit ล่าสุด แต่อย่างน้อยก็เป็นคอมไพเลอร์โฮสต์ล่าสุดของชุดเครื่องมือ CUDA เก่าที่รองรับ
เราอาจยังคงสนับสนุนคอมไพเลอร์เพิ่มเติมและจะยอมรับแพตช์ที่สอดคล้องกันจากชุมชนด้วยการแก้ไขที่สมเหตุสมผล แต่เราจะไม่ลงทุนเวลาอย่างมีนัยสำคัญในการสามหรือแก้ไขปัญหาสำหรับคอมไพเลอร์รุ่นเก่า
ด้วยจิตวิญญาณของ "คุณสนับสนุนสิ่งที่คุณทดสอบเท่านั้น" ดูภาพรวม CI ของเราสำหรับข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่เราทดสอบ
เว้นแต่จะระบุไว้เป็นอย่างอื่น CCCL รองรับสถาปัตยกรรม GPU/ความสามารถในการคำนวณที่เหมือนกันทั้งหมดเช่น CUDA Toolkit ซึ่งมีการบันทึกไว้ที่นี่: https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#compute-capability
โปรดทราบว่าคุณสมบัติบางอย่างอาจรองรับสถาปัตยกรรม/ความสามารถในการคำนวณบางอย่างเท่านั้น
กลยุทธ์การทดสอบของ CCCL ทำให้เกิดความสมดุลระหว่างการทดสอบการกำหนดค่าให้ได้มากที่สุดเท่าที่จะเป็นไปได้และรักษาเวลา CI ที่สมเหตุสมผล
สำหรับรุ่น CUDA Toolkit การทดสอบจะทำกับทั้งรุ่นที่เก่าแก่ที่สุดและรุ่นใหม่ล่าสุด ตัวอย่างเช่นหาก CUDA Toolkit เวอร์ชันล่าสุดคือ 12.3 การทดสอบจะดำเนินการกับ 11.1 และ 12.3 สำหรับแต่ละรุ่น CUDA การสร้างจะเสร็จสมบูรณ์กับคอมไพเลอร์โฮสต์ที่รองรับทั้งหมดด้วยภาษา C ++ ที่รองรับทั้งหมด
กลยุทธ์การทดสอบและเมทริกซ์มีการพัฒนาอย่างต่อเนื่อง เมทริกซ์ที่กำหนดไว้ในไฟล์ ci/matrix.yaml เป็นแหล่งที่มาของความจริงที่ชัดเจน สำหรับข้อมูลเพิ่มเติมเกี่ยวกับท่อส่ง CI ของเราดูที่นี่
วัตถุประสงค์: ส่วนนี้อธิบายถึงวิธีการที่ CCCL เป็นเวอร์ชันการรับประกันความเสถียรของ API/ABI และแนวทางความเข้ากันได้เพื่อลดอาการปวดหัวในการอัพเกรด
สรุป
cub:: หรือ thrust:: namespacescuda:: Namespace อาจเกิดขึ้นได้ตลอดเวลา แต่จะสะท้อนให้เห็นโดยการเพิ่มรุ่น ABI ซึ่งฝังอยู่ในเนมสเปซแบบอินไลน์สำหรับสัญลักษณ์ cuda:: ทั้งหมด อาจสนับสนุน ABI หลายรุ่นพร้อมกันหมายเหตุ: ก่อนที่จะรวมแรงขับ, Cub, และ libcudacxx ลงในที่เก็บนี้แต่ละห้องสมุดจะได้รับเวอร์ชันที่เป็นอิสระตามเวอร์ชันความหมาย เริ่มต้นด้วยการเปิดตัว 2.1 ห้องสมุดทั้งสามห้องได้ซิงโครไนซ์เวอร์ชันรุ่นของพวกเขาในที่เก็บแยกต่างหาก ก้าวไปข้างหน้า CCCL จะยังคงเปิดตัวภายใต้เวอร์ชันความหมายเดียวโดย 2.2.0 เป็นรุ่นแรกจากที่เก็บ NVIDIA/CCCL
การเปลี่ยนแปลงที่แตกคือการเปลี่ยนแปลงฟังก์ชั่น ที่ได้รับการสนับสนุนอย่างชัดเจน ระหว่างเวอร์ชันที่ปล่อยออกมาซึ่งจะทำให้ผู้ใช้ต้องทำงานเพื่ออัพเกรดเป็นเวอร์ชันใหม่
ในขีด จำกัด การเปลี่ยนแปลง ใด ๆ มีศักยภาพที่จะทำลายใครบางคน เป็นผลให้การเปลี่ยนแปลงการแตกหักของแหล่งที่เป็นไปได้ทั้งหมดถือเป็นการเปลี่ยนแปลงการเปลี่ยนแปลงของ API สาธารณะที่รับประกันการชนเวอร์ชันความหมายสำคัญ
ส่วนด้านล่างอธิบายรายละเอียดของการเปลี่ยนแปลงการเปลี่ยนแปลงของ API และ ABI ของ CCCL
API สาธารณะของ CCCL เป็นฟังก์ชั่นทั้งหมดที่เปิดเผย โดยเจตนา เพื่อให้ยูทิลิตี้ของห้องสมุด
กล่าวอีกนัยหนึ่ง API สาธารณะของ CCCL นั้นเกินกว่าฟังก์ชั่นลายเซ็นและรวมถึง (แต่ไม่ จำกัด เฉพาะ):
นอกจากนี้ API สาธารณะของ CCCL ไม่ได้ รวมสิ่งต่อไปนี้:
_ หรือ __detail รวมถึง detail:: เนมสเปซหรือแมโครdetail/ ไดเรกทอรีหรือไดเรกทอรีย่อยของมันโดยทั่วไปเป้าหมายคือการหลีกเลี่ยงการทำลายสิ่งใดใน API สาธารณะ การเปลี่ยนแปลงดังกล่าวเกิดขึ้นเฉพาะในกรณีที่พวกเขาเสนอประสิทธิภาพที่ดีขึ้นผู้ใช้ API ที่เข้าใจได้ง่ายขึ้นและ/หรือ API ที่สอดคล้องกันมากขึ้น
การเปลี่ยนแปลงใด ๆ ที่เกิดขึ้นกับ API สาธารณะจะต้องใช้หมายเลขเวอร์ชันหลักของ CCCL ที่ชนกัน เพื่อให้สอดคล้องกับความเข้ากันได้ของ Cuda Minor รุ่นการเปลี่ยนแปลงของ API และ CCCL Major Version Bumps จะเกิดขึ้นใกล้เคียงกับการเปิดตัว CUDA Toolkit รุ่นใหญ่รุ่นใหม่
อะไรก็ตามที่ไม่ได้เป็นส่วนหนึ่งของ API สาธารณะอาจเปลี่ยนแปลงได้ตลอดเวลาโดยไม่มีการเตือนล่วงหน้า
API สาธารณะของส่วนประกอบทั้งหมดของ CCCL แบ่งปันรุ่นความหมายแบบครบวงจรของ MAJOR.MINOR.PATCH
รองรับรุ่นที่เพิ่งเปิดตัวล่าสุดเท่านั้น ตามกฎแล้วคุณสมบัติและการแก้ไขข้อผิดพลาดจะไม่ถูกนำกลับไปใช้กับเวอร์ชันหรือสาขาที่วางจำหน่ายก่อนหน้านี้
วิธีที่ต้องการสำหรับการสอบถามเวอร์ชันคือการใช้ CCCL_[MAJOR/MINOR/PATCH_]VERSION ตามที่อธิบายไว้ด้านล่าง สำหรับความเข้ากันได้ย้อนหลังคำจำกัดความของเวอร์ชัน THRUST/CUB/LIBCUDACXXX นั้นมีอยู่และจะสอดคล้องกับ CCCL_VERSION เสมอ โปรดทราบว่าแรงขับ/Cub ใช้รูปแบบ MMMmmmpp ในขณะที่ CCCL และ LIBCUDACXX ใช้ MMMmmmppp
| CCCL | libcudacxx | แรงขับ | ลูก | |
|---|---|---|---|---|
| ส่วนหัว | <cuda/version> | <cuda/std/version> | <thrust/version.h> | <cub/version.h> |
| รุ่นใหญ่ | CCCL_MAJOR_VERSION | _LIBCUDACXX_CUDA_API_VERSION_MAJOR | THRUST_MAJOR_VERSION | CUB_MAJOR_VERSION |
| รุ่นรอง | CCCL_MINOR_VERSION | _LIBCUDACXX_CUDA_API_VERSION_MINOR | THRUST_MINOR_VERSION | CUB_MINOR_VERSION |
| เวอร์ชันแพตช์/ผู้ส่ง | CCCL_PATCH_VERSION | _LIBCUDACXX_CUDA_API_VERSION_PATCH | THRUST_SUBMINOR_VERSION | CUB_SUBMINOR_VERSION |
| เวอร์ชันที่ต่อกัน | CCCL_VERSION (MMMmmmppp) | _LIBCUDACXX_CUDA_API_VERSION (MMMmmmppp) | THRUST_VERSION (MMMmmmpp) | CUB_VERSION (MMMmmmpp) |
แอปพลิเคชันไบนารีอินเทอร์เฟซ (ABI) เป็นชุดของกฎสำหรับ:
ABI ของห้องสมุดรวมถึง แต่ไม่ จำกัด เพียง:
การเปลี่ยนแปลงการแตกหักของ ABI คือการเปลี่ยนแปลงใด ๆ ที่ส่งผลให้เกิดการเปลี่ยนแปลง ABI ของฟังก์ชั่นหรือประเภทใน API สาธารณะ ตัวอย่างเช่นการเพิ่มสมาชิกข้อมูลใหม่ไปยัง struct เป็นการเปลี่ยนแปลงการแตกหักของ ABI เนื่องจากมันเปลี่ยนขนาดของประเภท
ใน CCCL การรับประกันเกี่ยวกับ ABI มีดังนี้:
thrust:: และ cub:: เนมสเปซอาจทำลาย ABI ได้ตลอดเวลาโดยไม่มีการเตือนล่วงหน้าthrust:: และ cub:: สัญลักษณ์รวมถึงสถาปัตยกรรม CUDA ที่ใช้สำหรับการรวบรวม ดังนั้น thrust:: หรือ cub:: สัญลักษณ์อาจมี ABI ที่แตกต่างกันถ้า:-x cu ) vs c ++ แหล่งที่มา ( -x cpp )cuda:: namespace อาจทำลาย ABI ได้ตลอดเวลา อย่างไรก็ตาม cuda:: สัญลักษณ์ฝังหมายเลขเวอร์ชัน ABI ที่เพิ่มขึ้นทุกครั้งที่มีการหยุดพัก ABI อาจได้รับการสนับสนุนหลายเวอร์ชัน ABI พร้อมกันดังนั้นผู้ใช้จึงมีตัวเลือกในการเปลี่ยนกลับไปใช้เป็นรุ่น ABI ก่อนหน้า สำหรับข้อมูลเพิ่มเติมดูที่นี่ใครควรสนใจ Abi?
โดยทั่วไปผู้ใช้ CCCL จะต้องกังวลเกี่ยวกับปัญหา ABI เมื่อสร้างหรือใช้สิ่งประดิษฐ์ไบนารี (เช่นห้องสมุดที่ใช้ร่วมกัน) ซึ่ง API โดยตรงหรือโดยอ้อมรวมถึงประเภทที่จัดทำโดย CCCL
ตัวอย่างเช่นพิจารณาว่า libA.so ถูกสร้างขึ้นโดยใช้ CCCL เวอร์ชัน X และ API สาธารณะรวมถึงฟังก์ชั่นเช่น:
void foo (cuda::std::optional< int >); หากห้องสมุดอื่น libB.so ถูกรวบรวมโดยใช้ CCCL เวอร์ชัน Y และใช้ foo จาก libA.so สิ่งนี้อาจล้มเหลวหากมีการแบ่ง ABI ระหว่างรุ่น X และ Y ABI Breaks มักจะไม่ต้องการการเปลี่ยนแปลงรหัสและต้องการการรวมทุกอย่างเพื่อใช้ ABI รุ่นเดียวกัน
หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ ABI และทำไมจึงมีความสำคัญดูว่า ABI คืออะไรและ C ++ ควรทำอย่างไรกับมัน?
ดังที่ได้กล่าวไว้ข้างต้นการเปลี่ยนแปลงการทำลายแหล่งที่มาที่เป็นไปได้ทั้งหมดนั้นเป็นการเปลี่ยนแปลงที่เกิดขึ้นซึ่งจะต้องเพิ่มหมายเลขรุ่น API API ของ CCCL ที่เพิ่มขึ้น
ผู้ใช้จะได้รับการสนับสนุนให้ปฏิบัติตามแนวทางต่อไปนี้เพื่อลดความเสี่ยงของการหยุดชะงักของการหยุดชะงักโดยไม่ได้ตั้งใจขึ้นอยู่กับส่วนของ CCCL ที่ไม่ได้เป็นส่วนหนึ่งของ API สาธารณะ:
thrust:: , cub:: , nv:: หรือ cuda:: เนมสเปซเว้นแต่จะมีการบันทึกข้อยกเว้นสำหรับสัญลักษณ์เฉพาะเช่น cuda::std::iterator_traitsthrust:: , cub:: , cuda:: หรือ nv:: namespacesthrust:: , cub:: , cuda:: หรือ nv:: namespaces_ , __ หรือมี detail ใด ๆ ในชื่อรวมถึง detail:: เนมสเปซหรือมาโคร#include ไฟล์ส่วนหัวที่ประกาศสัญลักษณ์นั้นโดยตรง กล่าวอีกนัยหนึ่งอย่าพึ่งพาส่วนหัวโดยปริยายรวมโดยส่วนหัวอื่น ๆส่วนของส่วนนี้ได้รับแรงบันดาลใจจากแนวทางความเข้ากันได้ของ Abseil
เราจะพยายามอย่างดีที่สุดเพื่อแจ้งให้ผู้ใช้ทราบก่อนที่จะทำการเปลี่ยนแปลงใด ๆ กับ API สาธารณะ, ABI หรือแก้ไขแพลตฟอร์มและคอมไพเลอร์ที่รองรับ
ตามความเหมาะสมการคัดค้านจะมาในรูปแบบของคำเตือนแบบเป็นโปรแกรมซึ่งสามารถปิดใช้งานได้
ระยะเวลาการเสื่อมราคาจะขึ้นอยู่กับผลกระทบของการเปลี่ยนแปลง แต่โดยปกติจะมีการเผยแพร่รุ่นรองอย่างน้อย 2 รุ่น
เร็วๆ นี้!
สำหรับภาพรวมโดยละเอียดของท่อส่ง CI ให้ดู Ci-Overview.md
โครงการที่เกี่ยวข้องกับภารกิจของ CCCL เพื่อทำให้ Cuda มีความสุขมากขึ้น:
โครงการของคุณใช้ CCCL หรือไม่? เปิดประชาสัมพันธ์เพื่อเพิ่มโครงการของคุณในรายการนี้!
