offload.rs 60.3 KB
Newer Older
1
2
3
// SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

4
5
6
7
8
//! # Offload Manager
//! The offload manager is responsible for handling all block transfers between different cache levels.
//!
//! ## Offloading
//! Offloading is the process of moving blocks to a cache level further away from the device.
Ryan Olson's avatar
Ryan Olson committed
9
//! When blocks are registered (via [`ManagedBlockPool::register_blocks`]), they are automatically sent to the offload manager.
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
//! Due to limited bandwidth, the offload manager must prioritize which offloads to perform.
//! This is indicated by the `priority` parameter to [`OffloadManager::offload`].
//! When a offload request is received, the offload manager will enqueue it into a priority queue.
//! This priority queue is keyed by the `priority` parameter, where blocks with lower priority values are processed first.
//! Within the same priority, blocks that were sent to the offload manager earlier are processed first.
//!
//! ## Onboarding
//! Onboarding is the process of moving blocks to a cache level closer to the device.
//! All onboardings are manually triggered through the [`OffloadManager::onboard`] method.
//!
//! ## Transfer Managers
//! The offload manager uses two transfer managers to handle the offloading and onboarding of blocks.
//!
//! The [`CudaTransferManager`] is responsible for transfers between the device and host.
//! The [`DiskTransferManager`] is responsible for transfers from host to disk and disk to device.
//!
//! ## Worker Threads
//! The offload manager uses two kinds of worker threads to handle the offloading and onboarding of blocks.
//!
//! The [`OffloadManager::offload_worker`] is responsible for offloading blocks.
//! The [`OffloadManager::onboard_worker`] is responsible for onboarding blocks.
//!
//! The kind of offloads/onboards they perform is dictated by the source and target arguments
33
//! of the [`OffloadManager::offload_worker`] and [`OffloadManager::onboard_worker`] methods.
34

Ryan Olson's avatar
Ryan Olson committed
35
use super::block::{
36
    BlockError, BlockMetadata, BlockState, ImmutableBlock, MutableBlock,
37
38
    locality::LocalityProvider,
    transfer::{PoolConfig, TransferContext},
Ryan Olson's avatar
Ryan Olson committed
39
};
40
use super::metrics::{BlockManagerMetrics, PoolMetrics};
Ryan Olson's avatar
Ryan Olson committed
41
use super::pool::{BlockPool, BlockPoolError};
42
use super::storage::{Cuda, Storage};
43
use super::{DeviceStorage, DiskStorage, KvManagerModelConfig, PinnedStorage};
44
45
46
47
use nixl_sys::Agent as NixlAgent;
use std::sync::Arc;
use tokio::runtime::Handle;
use tokio::sync::{
48
    Mutex,
49
    mpsc::{self, error::TryRecvError},
50
    oneshot,
51
};
52
use tokio_util::sync::CancellationToken;
53
54
55
56
57
58
59

use anyhow::Result;
use std::any::Any;

use std::collections::BTreeSet;

mod pending;
60
pub mod request;
61

Ryan Olson's avatar
Ryan Olson committed
62
use pending::{LocalTransferManager, PendingTransfer, TransferBatcher, TransferManager};
63
use request::{BlockResult, OffloadRequest, OffloadRequestKey, OnboardRequest};
64

65
66
use dynamo_runtime::utils::task::CriticalTaskExecutionHandle;

67
68
69
70
71
72
73
74
75
76
77
pub const MAX_CONCURRENT_TRANSFERS: usize = 4;
pub const MAX_TRANSFER_BATCH_SIZE: usize = 16;

/// Configuration for creating an OffloadManager
pub struct OffloadManagerConfig {
    pub nixl_agent: Arc<Option<NixlAgent>>,
    pub async_rt_handle: Handle,
    pub metrics: Arc<BlockManagerMetrics>,
    pub cancellation_token: CancellationToken,
    pub model_config: KvManagerModelConfig,
}
78
79

/// The offload manager handles all block transfers between different cache levels.
Ryan Olson's avatar
Ryan Olson committed
80
pub struct OffloadManager<Locality: LocalityProvider, Metadata: BlockMetadata> {
81
    // Handles to the device, host, and disk pools.
Ryan Olson's avatar
Ryan Olson committed
82
83
84
    disk: Option<Arc<dyn BlockPool<DiskStorage, Locality, Metadata>>>,
    host: Option<Arc<dyn BlockPool<PinnedStorage, Locality, Metadata>>>,
    device: Option<Arc<dyn BlockPool<DeviceStorage, Locality, Metadata>>>,
85

86
    /// Queue of offloading requests.
Ryan Olson's avatar
Ryan Olson committed
87
88
    device_offload_tx: mpsc::UnboundedSender<OffloadRequest<DeviceStorage, Locality, Metadata>>,
    host_offload_tx: mpsc::UnboundedSender<OffloadRequest<PinnedStorage, Locality, Metadata>>,
89
90

    /// Queue of pending onboarding requests.
Ryan Olson's avatar
Ryan Olson committed
91
92
93
94
    host_onboard_tx:
        mpsc::UnboundedSender<OnboardRequest<PinnedStorage, DeviceStorage, Locality, Metadata>>,
    disk_onboard_tx:
        mpsc::UnboundedSender<OnboardRequest<DiskStorage, DeviceStorage, Locality, Metadata>>,
95
96
97

    /// An incrementing counter for offloaded blocks. Within the same priority, blocks with lower tick values are processed first.
    tick: Arc<Mutex<u64>>,
98
99
}

Ryan Olson's avatar
Ryan Olson committed
100
101
102
impl<Locality: LocalityProvider + 'static, Metadata: BlockMetadata>
    OffloadManager<Locality, Metadata>
{
103
    pub fn new(
Ryan Olson's avatar
Ryan Olson committed
104
105
106
        disk: Option<Arc<dyn BlockPool<DiskStorage, Locality, Metadata>>>,
        host: Option<Arc<dyn BlockPool<PinnedStorage, Locality, Metadata>>>,
        device: Option<Arc<dyn BlockPool<DeviceStorage, Locality, Metadata>>>,
107
        config: OffloadManagerConfig,
108
    ) -> Result<Arc<Self>> {
109
110
111
112
113
        let (device_offload_tx, device_offload_rx) = mpsc::unbounded_channel();
        let (host_offload_tx, host_offload_rx) = mpsc::unbounded_channel();

        let (host_onboard_tx, host_onboard_rx) = mpsc::unbounded_channel();
        let (disk_onboard_tx, disk_onboard_rx) = mpsc::unbounded_channel();
114
115

        let this = Arc::new(Self {
116
            disk,
117
            host,
118
119
120
121
122
            device,
            device_offload_tx,
            host_offload_tx,
            host_onboard_tx,
            disk_onboard_tx,
123
124
125
            tick: Arc::new(Mutex::new(0)),
        });

126
        let cuda_ctx = Cuda::device_or_create(0)?;
127

128
129
130
131
132
133
134
135
        let pool_config = PoolConfig {
            enable_pool: true,
            max_concurrent_transfers: MAX_CONCURRENT_TRANSFERS,
            max_transfer_batch_size: MAX_TRANSFER_BATCH_SIZE,
            num_outer_components: config.model_config.outer_dim,
            num_layers: config.model_config.num_layers,
        };

136
137
        // We want cuda offloads to happen in parallel with host onboards, so we need to use a different stream.
        let device_offload_transfer_ctx = Arc::new(TransferContext::new(
138
            config.nixl_agent.clone(),
139
            cuda_ctx.new_stream()?,
140
141
            config.async_rt_handle.clone(),
            Some(pool_config),
142
        ));
143

144
145
146
        let device_metrics = config.metrics.pool("device");
        let host_metrics = config.metrics.pool("host");
        let disk_metrics = config.metrics.pool("disk");
Ryan Olson's avatar
Ryan Olson committed
147

148
        // Device -> Host offload
149
150
151
152
153
        let device_to_host_task = OffloadManager::offload_worker(
            this.device.clone(),
            this.host.clone(),
            device_offload_rx,
            Arc::new(TransferBatcher::new(
Ryan Olson's avatar
Ryan Olson committed
154
                LocalTransferManager::new(
155
156
                    device_offload_transfer_ctx,
                    MAX_CONCURRENT_TRANSFERS,
157
158
                    &config.async_rt_handle,
                    config.cancellation_token.clone(),
Ryan Olson's avatar
Ryan Olson committed
159
160
                    device_metrics.clone(),
                    "offload_bw".to_string(),
161
                )?,
162
                MAX_TRANSFER_BATCH_SIZE,
163
164
                &config.async_rt_handle,
                config.cancellation_token.clone(),
165
            )),
Ryan Olson's avatar
Ryan Olson committed
166
            device_metrics.clone(),
167
            config.cancellation_token.clone(),
168
169
170
        );
        CriticalTaskExecutionHandle::new_with_runtime(
            |_| device_to_host_task,
171
            config.cancellation_token.clone(),
172
            "Device -> Host offload worker",
173
            &config.async_rt_handle,
174
175
        )?
        .detach();
176

177
        let transfer_ctx = Arc::new(TransferContext::new(
178
            config.nixl_agent.clone(),
179
            cuda_ctx.new_stream()?,
180
181
            config.async_rt_handle.clone(),
            None,
182
        ));
183

184
        // Host -> Disk offload
185
186
187
188
189
        let host_to_disk_task = OffloadManager::offload_worker(
            this.host.clone(),
            this.disk.clone(),
            host_offload_rx,
            Arc::new(TransferBatcher::new(
Ryan Olson's avatar
Ryan Olson committed
190
                LocalTransferManager::new(
191
192
                    transfer_ctx.clone(),
                    MAX_CONCURRENT_TRANSFERS,
193
194
                    &config.async_rt_handle,
                    config.cancellation_token.clone(),
Ryan Olson's avatar
Ryan Olson committed
195
196
                    host_metrics.clone(),
                    "offload_bw".to_string(),
197
                )?,
198
                MAX_TRANSFER_BATCH_SIZE,
199
200
                &config.async_rt_handle,
                config.cancellation_token.clone(),
201
            )),
Ryan Olson's avatar
Ryan Olson committed
202
            host_metrics.clone(),
203
            config.cancellation_token.clone(),
204
205
206
        );
        CriticalTaskExecutionHandle::new_with_runtime(
            |_| host_to_disk_task,
207
            config.cancellation_token.clone(),
208
            "Host -> Disk offload worker",
209
            &config.async_rt_handle,
210
211
        )?
        .detach();
212

213
        // Host -> Device onboarding
214
215
216
217
218
        let host_to_device_task = OffloadManager::onboard_worker(
            this.host.clone(),
            this.device.clone(),
            host_onboard_rx,
            Arc::new(TransferBatcher::new(
Ryan Olson's avatar
Ryan Olson committed
219
                LocalTransferManager::new(
220
221
                    transfer_ctx.clone(),
                    MAX_CONCURRENT_TRANSFERS,
222
223
                    &config.async_rt_handle,
                    config.cancellation_token.clone(),
Ryan Olson's avatar
Ryan Olson committed
224
225
                    host_metrics.clone(),
                    "onboard_bw".to_string(),
226
                )?,
227
                MAX_TRANSFER_BATCH_SIZE,
228
229
                &config.async_rt_handle,
                config.cancellation_token.clone(),
230
            )),
Ryan Olson's avatar
Ryan Olson committed
231
            host_metrics.clone(),
232
            config.cancellation_token.clone(),
233
234
235
        );
        CriticalTaskExecutionHandle::new_with_runtime(
            |_| host_to_device_task,
236
            config.cancellation_token.clone(),
237
            "Host -> Device onboarding worker",
238
            &config.async_rt_handle,
239
240
        )?
        .detach();
241

242
        // Disk -> Device onboarding
243
244
245
246
247
        let disk_to_device_task = OffloadManager::onboard_worker(
            this.disk.clone(),
            this.device.clone(),
            disk_onboard_rx,
            Arc::new(TransferBatcher::new(
Ryan Olson's avatar
Ryan Olson committed
248
                LocalTransferManager::new(
249
250
                    transfer_ctx.clone(),
                    MAX_CONCURRENT_TRANSFERS,
251
252
                    &config.async_rt_handle,
                    config.cancellation_token.clone(),
Ryan Olson's avatar
Ryan Olson committed
253
254
                    disk_metrics.clone(),
                    "onboard_bw".to_string(),
255
                )?,
256
                MAX_TRANSFER_BATCH_SIZE,
257
258
                &config.async_rt_handle,
                config.cancellation_token.clone(),
259
            )),
Ryan Olson's avatar
Ryan Olson committed
260
            disk_metrics.clone(),
261
            config.cancellation_token.clone(),
262
263
264
        );
        CriticalTaskExecutionHandle::new_with_runtime(
            |_| disk_to_device_task,
265
            config.cancellation_token.clone(),
266
            "Disk -> Device onboarding worker",
267
            &config.async_rt_handle,
268
269
        )?
        .detach();
270

271
        Ok(this)
272
    }
273

274
    async fn offload_worker<Source: Storage, Target: Storage>(
Ryan Olson's avatar
Ryan Olson committed
275
276
277
278
        source_pool: Option<Arc<dyn BlockPool<Source, Locality, Metadata>>>,
        target_pool: Option<Arc<dyn BlockPool<Target, Locality, Metadata>>>,
        mut offload_rx: mpsc::UnboundedReceiver<OffloadRequest<Source, Locality, Metadata>>,
        transfer_manager: Arc<dyn TransferManager<Source, Target, Locality, Metadata>>,
279
        pool_metrics: Arc<PoolMetrics>,
280
        cancellation_token: CancellationToken,
281
    ) -> Result<()> {
282
        if source_pool.is_none() || target_pool.is_none() {
283
284
285
            return Ok(());
        }

286
287
        let source_pool = source_pool.as_ref().unwrap();
        let target_pool = target_pool.as_ref().unwrap();
288

289
        let mut queue = BTreeSet::new();
290
291

        loop {
292
293
294
295
            if cancellation_token.is_cancelled() {
                return Ok(());
            }

296
            // Try to check the offload queue.
297
298
299
300
            loop {
                match offload_rx.try_recv() {
                    Ok(request) => {
                        queue.insert(request);
301
                        pool_metrics.gauge("offload_queue_size").inc();
302
303
304
305
                    }
                    Err(TryRecvError::Empty) => {
                        break;
                    }
306
                    Err(e) => return Err(e.into()),
307
308
                }
            }
309
310

            // If there is a request, process it.
311
            if let Some(request) = queue.pop_first() {
312
                pool_metrics.gauge("offload_queue_size").dec();
313
314
                // Try to upgrade the block to a strong reference.
                let block = match request.block.upgrade() {
Ryan Olson's avatar
Ryan Olson committed
315
                    Some(block) => Some(ImmutableBlock::new(block)),
316
                    // If unable to upgrade, the block may have been moved to the inactive pool.
317
                    None => source_pool
318
319
                        .match_sequence_hashes(vec![request.sequence_hash].as_slice())
                        .await?
Ryan Olson's avatar
Ryan Olson committed
320
                        .pop(),
321
322
                };

323
                // If we've found the block, offload it.
324
                if let Some(block) = block {
325
326
                    // If the block is already in the target, don't offload it.
                    if let Ok(blocks) = target_pool
Ryan Olson's avatar
Ryan Olson committed
327
328
                        .match_sequence_hashes(vec![request.sequence_hash].as_slice())
                        .await
329
                        && !blocks.is_empty()
330
                    {
331
                        continue;
332
333
                    }

334
                    let target_block = 'target_block: {
335
336
337
338
                        if let Ok(blocks) = target_pool.allocate_blocks(1).await
                            && let Some(block) = blocks.into_iter().next()
                        {
                            break 'target_block Some(block);
339
                        }
340

341
342
343
                        tracing::warn!(
                            "Target pool full. Skipping offload. This should only ever happen with very small pool sizes."
                        );
344
                        None
345
346
                    };

347
                    if let Some(target_block) = target_block {
348
                        pool_metrics.counter("offload_processed").inc();
Ryan Olson's avatar
Ryan Olson committed
349
350
351
352
                        tracing::debug!(
                            "Offloading block with sequence hash {} to target pool.",
                            request.sequence_hash
                        );
353
                        transfer_manager
354
                            .enqueue_transfer(PendingTransfer::new(
355
                                vec![block],
356
                                vec![target_block],
357
                                None,
358
                                target_pool.clone(),
359
360
361
362
363
                            ))
                            .await?;
                    }
                }
            } else {
364
                // Await the next request.
365
366
367
368
                tokio::select! {
                    _ = cancellation_token.cancelled() => return Ok(()),
                    Some(request) = offload_rx.recv() => {
                        queue.insert(request);
369
                        pool_metrics.gauge("offload_queue_size").inc();
370
                    }
371
                }
372
373
374
375
            }
        }
    }

376
    async fn onboard_worker<Source: Storage, Target: Storage>(
Ryan Olson's avatar
Ryan Olson committed
377
378
379
380
        source_pool: Option<Arc<dyn BlockPool<Source, Locality, Metadata>>>,
        target_pool: Option<Arc<dyn BlockPool<Target, Locality, Metadata>>>,
        mut onboard_rx: mpsc::UnboundedReceiver<OnboardRequest<Source, Target, Locality, Metadata>>,
        transfer_manager: Arc<dyn TransferManager<Source, Target, Locality, Metadata>>,
381
        pool_metrics: Arc<PoolMetrics>,
382
        cancellation_token: CancellationToken,
383
    ) -> Result<()> {
384
        if source_pool.is_none() || target_pool.is_none() {
385
386
387
            return Ok(());
        }

388
        let target_pool = target_pool.as_ref().unwrap();
389
390
391
392
        loop {
            tokio::select! {
                _ = cancellation_token.cancelled() => return Ok::<(), anyhow::Error>(()),
                Some(request) = onboard_rx.recv() => {
393
394
395
396
397

                    pool_metrics
                        .gauge("onboard_queue_size")
                        .set(onboard_rx.len() as i64);

398
                    // Try to allocate blocks on the device.
Ryan Olson's avatar
Ryan Olson committed
399
400
401
402
403
404
405
406
407
                    let target_blocks = if let Some(targets) = request.targets {
                        targets
                    } else {
                            match target_pool.allocate_blocks(request.blocks.len()).await {
                            Ok(blocks) => blocks,
                            Err(err) => {
                                let _ = request.response_tx.send(Err(err));
                                continue;
                            }
408
409
                        }
                    };
410

411
412
413
414
                    pool_metrics
                        .counter("onboard_processed")
                        .inc_by(request.blocks.len() as u64);

Ryan Olson's avatar
Ryan Olson committed
415
                    tracing::debug!("Onboarding {} blocks to target pool.", request.blocks.len());
416
417
418

                    transfer_manager
                        .enqueue_transfer(PendingTransfer::new(
Ryan Olson's avatar
Ryan Olson committed
419
                            request.blocks,
420
421
422
423
424
425
426
                            target_blocks,
                            Some(request.response_tx),
                            target_pool.clone(),
                        ))
                        .await?;

                    Ok::<(), anyhow::Error>(())
427
                }
428
            }?;
429
430
431
432
433
        }
    }

    pub async fn offload<S: Storage>(
        &self,
Ryan Olson's avatar
Ryan Olson committed
434
        block: &ImmutableBlock<S, Locality, Metadata>,
435
436
437
        priority: u64,
    ) -> core::result::Result<(), BlockPoolError> {
        match block.state() {
438
            BlockState::Registered(_, _) => {}
439
440
441
442
443
444
            _ => {
                return Err(BlockPoolError::BlockError(BlockError::InvalidState(
                    "Block is not registered.".to_string(),
                )));
            }
        }
445
446
447
448
449
450
451
452
453
454

        let mut tick = self.tick.lock().await;
        let key = OffloadRequestKey {
            priority,
            timestamp: *tick,
        };
        // Increment a counter for each block. Within the same priority, blocks with lower counter values are processed first.
        *tick += 1;
        drop(tick);

455
456
457
458
459
460
        // This can get called by all pools, regardless of whether or not they have a place to offload to.
        // Because of this, we need to check the block type here.
        let any_block = block as &dyn Any;

        // TODO: What's the performance penalty of this runtime type-checking?
        if let Some(device_block) =
Ryan Olson's avatar
Ryan Olson committed
461
            any_block.downcast_ref::<ImmutableBlock<DeviceStorage, Locality, Metadata>>()
462
        {
463
464
465
466
            // The host pool doesn't exist, so we can't offload to it.
            if self.device_offload_tx.is_closed() {
                return Ok(());
            }
467
468
469

            let request = OffloadRequest {
                block: Arc::downgrade(device_block.mutable_block()),
Ryan Olson's avatar
Ryan Olson committed
470
                sequence_hash: device_block.sequence_hash(),
471
472
473
                key,
            };

474
475
            self.device_offload_tx.send(request).unwrap();
        } else if let Some(host_block) =
Ryan Olson's avatar
Ryan Olson committed
476
            any_block.downcast_ref::<ImmutableBlock<PinnedStorage, Locality, Metadata>>()
477
478
479
480
481
482
483
484
        {
            // The disk pool doesn't exist, so we can't offload to it.
            if self.host_offload_tx.is_closed() {
                return Ok(());
            }

            let request = OffloadRequest {
                block: Arc::downgrade(host_block.mutable_block()),
Ryan Olson's avatar
Ryan Olson committed
485
                sequence_hash: host_block.sequence_hash(),
486
487
488
489
                key,
            };

            self.host_offload_tx.send(request).unwrap();
490
491
492
493
494
        }

        Ok(())
    }

Ryan Olson's avatar
Ryan Olson committed
495
    pub fn onboard<S: Storage>(
496
        &self,
Ryan Olson's avatar
Ryan Olson committed
497
498
499
500
        blocks: Vec<ImmutableBlock<S, Locality, Metadata>>,
        targets: Option<Vec<MutableBlock<DeviceStorage, Locality, Metadata>>>,
    ) -> oneshot::Receiver<BlockResult<DeviceStorage, Locality, Metadata>> {
        let (tx, rx) = oneshot::channel();
501
502
        for block in &blocks {
            match block.state() {
503
                BlockState::Registered(_, _) => {}
504
                _ => {
Ryan Olson's avatar
Ryan Olson committed
505
                    tx.send(Err(BlockPoolError::BlockError(BlockError::InvalidState(
506
                        "Block is not registered.".to_string(),
Ryan Olson's avatar
Ryan Olson committed
507
508
509
                    ))))
                    .unwrap();
                    return rx;
510
511
512
513
                }
            }
        }

514
515
516
517
518
519
520
521
        if let Some(targets) = targets.as_ref()
            && targets.len() != blocks.len()
        {
            tx.send(Err(BlockPoolError::BlockError(BlockError::Other(
                anyhow::anyhow!("Number of targets does not match number of blocks."),
            ))))
            .unwrap();
            return rx;
522
523
        }

Ryan Olson's avatar
Ryan Olson committed
524
525
526
527
        if blocks.is_empty() {
            tx.send(Ok(vec![])).unwrap();
            return rx;
        }
528

529
530
531
532
        let any_block = blocks.first().unwrap() as &dyn Any;

        // TODO: This is really ugly.
        if any_block
Ryan Olson's avatar
Ryan Olson committed
533
            .downcast_ref::<ImmutableBlock<PinnedStorage, Locality, Metadata>>()
534
535
536
537
538
539
            .is_some()
        {
            let host_blocks = blocks
                .iter()
                .map(|b| {
                    (b as &dyn Any)
Ryan Olson's avatar
Ryan Olson committed
540
                        .downcast_ref::<ImmutableBlock<PinnedStorage, Locality, Metadata>>()
541
542
543
544
545
                        .unwrap()
                        .clone()
                })
                .collect();

Ryan Olson's avatar
Ryan Olson committed
546
547
548
549
550
551
552
553
            if let Err(e) = self
                .host_onboard_tx
                .send(OnboardRequest::new(host_blocks, tx, targets))
            {
                e.0.response_tx
                    .send(Err(BlockPoolError::ProgressEngineShutdown))
                    .unwrap();
            }
554
        } else if any_block
Ryan Olson's avatar
Ryan Olson committed
555
            .downcast_ref::<ImmutableBlock<DiskStorage, Locality, Metadata>>()
556
557
558
559
560
561
            .is_some()
        {
            let disk_blocks = blocks
                .iter()
                .map(|b| {
                    (b as &dyn Any)
Ryan Olson's avatar
Ryan Olson committed
562
                        .downcast_ref::<ImmutableBlock<DiskStorage, Locality, Metadata>>()
563
564
565
566
567
                        .unwrap()
                        .clone()
                })
                .collect();

Ryan Olson's avatar
Ryan Olson committed
568
569
570
571
572
573
574
575
            if let Err(e) = self
                .disk_onboard_tx
                .send(OnboardRequest::new(disk_blocks, tx, targets))
            {
                e.0.response_tx
                    .send(Err(BlockPoolError::ProgressEngineShutdown))
                    .unwrap();
            }
576
        } else {
Ryan Olson's avatar
Ryan Olson committed
577
            tx.send(Err(BlockPoolError::BlockError(BlockError::Other(
578
                anyhow::anyhow!("Block type not supported for onboarding."),
Ryan Olson's avatar
Ryan Olson committed
579
580
            ))))
            .unwrap();
581
582
        }

Ryan Olson's avatar
Ryan Olson committed
583
        rx
584
585
586
587
    }
}

#[cfg(all(test, feature = "testing-cuda"))]
Ryan Olson's avatar
Ryan Olson committed
588
mod tests {
589
590
591
    use super::*;

    use crate::block_manager::{
592
        LayoutConfig, NixlRegisterableStorage,
593
        block::{
594
            BasicMetadata, BlockDataExt, BlockDataProvider, Blocks, MutableBlock, locality::Local,
595
        },
596
        layout::{FullyContiguous, LayerSeparate, LayoutType, nixl::NixlLayout},
Ryan Olson's avatar
Ryan Olson committed
597
        pool::{BlockRegistrationDuplicationSetting, ManagedBlockPool},
598
        storage::{
599
            DeviceAllocator, DeviceStorage, DiskAllocator, DiskStorage, PinnedAllocator,
Ryan Olson's avatar
Ryan Olson committed
600
            PinnedStorage, StorageAllocator, StorageType,
601
602
        },
    };
603
    use crate::tokens::{TokenBlockSequence, Tokens};
604
    use nixl_sys::{MemoryRegion, NixlDescriptor};
605

606
    use aligned_vec::avec;
607
    use cudarc::runtime::sys::{cudaMemcpy, cudaMemcpyKind, cudaMemset};
608
    use prometheus::Registry;
Ryan Olson's avatar
Ryan Olson committed
609
    use rstest::*;
610
    use std::fs::File;
611
    use std::io::{Read, Seek, SeekFrom, Write};
612
613
    use std::mem::ManuallyDrop;
    use std::os::unix::io::FromRawFd;
614
615

    const BLOCK_SIZE: usize = 4;
616
    const NUM_LAYERS: usize = 8;
617

Ryan Olson's avatar
Ryan Olson committed
618
619
620
    type DevicePool = Option<Arc<dyn BlockPool<DeviceStorage, Local, BasicMetadata>>>;
    type HostPool = Option<Arc<dyn BlockPool<PinnedStorage, Local, BasicMetadata>>>;
    type DiskPool = Option<Arc<dyn BlockPool<DiskStorage, Local, BasicMetadata>>>;
621
622
623
624
625

    lazy_static::lazy_static! {
        static ref NIXL_AGENT: Arc<Option<NixlAgent>> = {
            let agent = NixlAgent::new("offload-manager").unwrap();
            let (_, ucx_params) = agent.get_plugin_params("UCX").unwrap();
Ryan Olson's avatar
Ryan Olson committed
626
            let (_, gds_mt_params) = agent.get_plugin_params("GDS_MT").unwrap();
627
            let (_, posix_params) = agent.get_plugin_params("POSIX").unwrap();
628
            agent.create_backend("UCX", &ucx_params).unwrap();
Ryan Olson's avatar
Ryan Olson committed
629
            agent.create_backend("GDS_MT", &gds_mt_params).unwrap();
630
            agent.create_backend("POSIX", &posix_params).unwrap();
631
632
633
            Arc::new(Some(agent))
        };
    }
634

Ryan Olson's avatar
Ryan Olson committed
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
    fn build_layout<S: Storage + NixlRegisterableStorage>(
        config: LayoutConfig,
        layout_type: LayoutType,
        agent: &NixlAgent,
        allocator: &dyn StorageAllocator<S>,
        duplication_setting: BlockRegistrationDuplicationSetting,
    ) -> Result<Arc<dyn BlockPool<S, Local, BasicMetadata>>> {
        match layout_type {
            LayoutType::FullyContiguous => {
                let mut pool_layout = FullyContiguous::allocate(config.clone(), allocator)?;
                pool_layout.nixl_register(agent, None)?;
                let blocks = Blocks::new(pool_layout, 42, 0)?.into_blocks()?;
                Ok(Arc::new(
                    ManagedBlockPool::builder()
                        .blocks(blocks)
                        .default_duplication_setting(duplication_setting)
                        .build()?,
                ))
            }
            LayoutType::LayerSeparate { outer_contiguous } => {
                let mut pool_layout =
                    LayerSeparate::allocate(config.clone(), allocator, outer_contiguous)?;
                pool_layout.nixl_register(agent, None)?;
                let blocks = Blocks::new(pool_layout, 42, 0)?.into_blocks()?;
                Ok(Arc::new(
                    ManagedBlockPool::builder()
                        .blocks(blocks)
                        .default_duplication_setting(duplication_setting)
                        .build()?,
                ))
            }
        }
    }

    #[allow(clippy::type_complexity)]
    fn build_pools(
671
672
        device_blocks: usize,
        host_blocks: Option<usize>,
673
        disk_blocks: Option<usize>,
674
        inner_dim: Option<usize>,
675
    ) -> Result<(
Ryan Olson's avatar
Ryan Olson committed
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
        Arc<OffloadManager<Local, BasicMetadata>>,
        DevicePool,
        HostPool,
        DiskPool,
    )> {
        build_pools_with_layout(
            device_blocks,
            host_blocks,
            disk_blocks,
            inner_dim,
            LayoutType::FullyContiguous,
            BlockRegistrationDuplicationSetting::Disabled,
        )
    }

    #[allow(clippy::type_complexity)]
    pub fn build_pools_with_layout(
        device_blocks: usize,
        host_blocks: Option<usize>,
        disk_blocks: Option<usize>,
        inner_dim: Option<usize>,
        layout_type: LayoutType,
        duplication_setting: BlockRegistrationDuplicationSetting,
    ) -> Result<(
        Arc<OffloadManager<Local, BasicMetadata>>,
701
702
703
704
        DevicePool,
        HostPool,
        DiskPool,
    )> {
705
706
        let mut config = LayoutConfig {
            num_blocks: device_blocks,
707
            num_layers: NUM_LAYERS,
708
            outer_dim: 1,
709
            page_size: BLOCK_SIZE,
710
            inner_dim: inner_dim.unwrap_or(1024),
711
            alignment: 1,
Ryan Olson's avatar
Ryan Olson committed
712
            dtype_width_bytes: 2,
713
714
        };

715
716
717
        let agent_arc = NIXL_AGENT.clone();
        let agent = agent_arc.as_ref().as_ref().unwrap();

Ryan Olson's avatar
Ryan Olson committed
718
719
720
721
722
723
724
        let device_pool = Some(build_layout(
            config.clone(),
            layout_type,
            agent,
            &DeviceAllocator::default(),
            duplication_setting,
        )?);
725
726
727

        let host_pool = if let Some(host_blocks) = host_blocks {
            config.num_blocks = host_blocks;
Ryan Olson's avatar
Ryan Olson committed
728
729
730
731
732
733
734
            Some(build_layout(
                config.clone(),
                layout_type,
                agent,
                &PinnedAllocator::default(),
                duplication_setting,
            )?)
735
        } else {
736
            None
737
738
        };

739
740
        let disk_pool = if let Some(disk_blocks) = disk_blocks {
            config.num_blocks = disk_blocks;
Ryan Olson's avatar
Ryan Olson committed
741
742
743
744
745
746
747
            Some(build_layout(
                config,
                layout_type,
                agent,
                &DiskAllocator,
                duplication_setting,
            )?)
748
        } else {
749
            None
750
        };
751

752
753
        let async_rt_handle = Handle::current();

754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
        let minimal_config = KvManagerModelConfig::builder()
            .num_layers(config.num_layers)
            .outer_dim(config.outer_dim) // K and V
            .page_size(config.page_size) // Minimal page size
            .inner_dim(config.inner_dim) // Small inner dim
            .build()
            .expect("Failed to build minimal config");

        let config = OffloadManagerConfig {
            nixl_agent: agent_arc,
            async_rt_handle,
            metrics: BlockManagerMetrics::new(&Arc::new(Registry::new()))?,
            cancellation_token: CancellationToken::new(),
            model_config: minimal_config,
        };

770
771
772
773
        let manager = OffloadManager::new(
            disk_pool.clone(),
            host_pool.clone(),
            device_pool.clone(),
774
            config,
775
776
777
        )?;

        Ok((manager, device_pool, host_pool, disk_pool))
778
779
780
    }

    /// Create a block in the 'RESET' state.
Ryan Olson's avatar
Ryan Olson committed
781
    #[expect(dead_code)]
782
    async fn get_block<S: Storage, Metadata: BlockMetadata>(
Ryan Olson's avatar
Ryan Olson committed
783
784
785
786
        pool: &Arc<dyn BlockPool<S, Local, Metadata>>,
    ) -> Result<MutableBlock<S, Local, Metadata>> {
        let mut blocks = pool.allocate_blocks(1).await?;
        Ok(blocks.pop().unwrap())
787
788
789
790
    }

    /// Create a block in the 'COMPLETED' state.
    async fn completed_block<S: Storage, Metadata: BlockMetadata>(
Ryan Olson's avatar
Ryan Olson committed
791
        pool: &Arc<dyn BlockPool<S, Local, Metadata>>,
792
        tokens: [u32; BLOCK_SIZE],
Ryan Olson's avatar
Ryan Olson committed
793
794
795
796
797
798
799
800
    ) -> Result<MutableBlock<S, Local, Metadata>> {
        let mut block = pool
            .allocate_blocks(1)
            .await?
            .into_iter()
            .next()
            .ok_or(anyhow::anyhow!("Failed to allocate block"))?;

801
802
803
804
805
806
807
808
        block.init_sequence(42)?;
        for token in tokens {
            block.add_token(token)?;
        }
        block.commit()?;
        Ok(block)
    }

809
    fn populate_block<S: Storage + NixlDescriptor>(
810
        block: &impl BlockDataProvider<StorageType = S>,
Ryan Olson's avatar
Ryan Olson committed
811
        start_value: u8,
812
    ) -> Result<()> {
Ryan Olson's avatar
Ryan Olson committed
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
        let block_data = block.block_data();

        let mut value = start_value;

        for layer_idx in 0..block_data.num_layers() {
            for outer_idx in 0..block_data.num_outer_dims() {
                let layer_view = block_data.layer_view(layer_idx, outer_idx)?;
                match block_data.storage_type() {
                    StorageType::Device(_) | StorageType::Pinned => unsafe {
                        cudaMemset(
                            layer_view.as_ptr() as *mut std::ffi::c_void,
                            value as i32,
                            layer_view.size(),
                        )
                        .result()?;
                    },
                    StorageType::Disk(_) => {
                        let nixl_desc = layer_view.as_nixl_descriptor();
                        let mut file: ManuallyDrop<File>;
                        let data = avec![[4096] | value; layer_view.size()];

                        unsafe {
                            file =
                                ManuallyDrop::new(File::from_raw_fd(nixl_desc.device_id() as i32));
                            file.seek(SeekFrom::Start(nixl_desc.as_ptr() as u64))?;
                        }
                        file.write_all(&data)?;
                        file.sync_all()?;
                        file.flush()?;
                    }
                    _ => panic!(),
844
845
                }
            }
Ryan Olson's avatar
Ryan Olson committed
846
847

            value += 1;
848
        }
849

850
851
852
        Ok(())
    }

853
854
    fn get_block_contents<S: Storage + NixlDescriptor>(
        block: &impl BlockDataProvider<StorageType = S>,
Ryan Olson's avatar
Ryan Olson committed
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
    ) -> Result<Vec<Vec<u8>>> {
        let block_data = block.block_data();

        let mut contents: Vec<Vec<u8>> = Vec::new();

        for layer_idx in 0..block_data.num_layers() {
            for outer_idx in 0..block_data.num_outer_dims() {
                let layer_view = block_data.layer_view(layer_idx, outer_idx)?;
                match block_data.storage_type() {
                    StorageType::Device(_) => unsafe {
                        let mut buffer = vec![0_u8; layer_view.size()];

                        cudaMemcpy(
                            buffer.as_mut_ptr() as *mut std::ffi::c_void,
                            layer_view.as_ptr() as *const std::ffi::c_void,
                            layer_view.size(),
                            cudaMemcpyKind::cudaMemcpyDeviceToHost,
                        )
                        .result()?;

                        contents.push(buffer);
                    },
                    StorageType::Pinned => unsafe {
                        contents.push(
                            std::slice::from_raw_parts(layer_view.as_ptr(), layer_view.size())
                                .to_vec(),
                        );
                    },
                    StorageType::Disk(_) => {
                        let nixl_desc = layer_view.as_nixl_descriptor();
                        let mut file: ManuallyDrop<File>;
                        let mut aligned = avec![[4096] | 0; layer_view.size()];

                        unsafe {
                            file =
                                ManuallyDrop::new(File::from_raw_fd(nixl_desc.device_id() as i32));
                            file.seek(SeekFrom::Start(nixl_desc.as_ptr() as u64))?;
                        }
                        file.read_exact(&mut aligned)?;
                        contents.push(aligned.to_vec());
                    }
                    _ => anyhow::bail!("Unsupported storage type."),
897
898
                }
            }
899
900
        }

Ryan Olson's avatar
Ryan Olson committed
901
        Ok(contents)
902
903
    }

904
    fn check_block_contents(
905
906
        block1: &impl BlockDataProvider<StorageType = impl Storage + NixlDescriptor>,
        block2: &impl BlockDataProvider<StorageType = impl Storage + NixlDescriptor>,
Ryan Olson's avatar
Ryan Olson committed
907
        start_value: u8,
908
    ) -> Result<()> {
909
910
        let contents1 = get_block_contents(block1)?;
        let contents2 = get_block_contents(block2)?;
911

Ryan Olson's avatar
Ryan Olson committed
912
913
914
915
916
917
918
919
920
        assert_eq!(contents1.len(), contents2.len());

        let mut value = start_value;

        for (layer1_vec, layer2_vec) in contents1.iter().zip(contents2.iter()) {
            for (c1_value, c2_value) in layer1_vec.iter().zip(layer2_vec.iter()) {
                if c1_value != c2_value || c1_value != &value {
                    panic!("{} != {} != {}", c1_value, c2_value, value);
                }
921
            }
Ryan Olson's avatar
Ryan Olson committed
922
            value += 1;
923
        }
924
925
926
927
928
        Ok(())
    }

    #[tokio::test]
    async fn test_offload_invalid_blocks() -> Result<()> {
929
        let (offload_manager, device_pool, _, _) = build_pools(4, Some(4), None, None)?;
930

931
        let device_pool = device_pool.as_ref().unwrap();
932
933
934
935
936
937
938
939
940
941
942
943
944
945

        // Check blocks in the 'COMPLETED' state.
        let immutable_block = ImmutableBlock::new(Arc::new(
            completed_block(device_pool, [0; BLOCK_SIZE]).await?,
        ));
        assert!(matches!(
            offload_manager.offload(&immutable_block, 0).await,
            Err(BlockPoolError::BlockError(BlockError::InvalidState(_)))
        ));

        Ok(())
    }

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
946
947
948
949
950
951
952
953
954
955
956
957
958
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_offload_registered_blocks(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools_with_layout(
            4,
            Some(4),
            None,
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
959

960
961
        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
962
963
964
965
966
967
968
969
970
971
972

        // Create a block and register it with the offload manager
        let block = completed_block(device_pool, [0, 1, 2, 3]).await?;

        let immutable_device_block = device_pool
            .register_blocks(vec![block])
            .await?
            .into_iter()
            .next()
            .ok_or(anyhow::anyhow!("Failed to register block"))?;

973
        populate_block(&immutable_device_block, 42)?;
974
975
976
977
978
979
980
981
982
983
984

        // Offloads should only go to G2 (for now)
        offload_manager.offload(&immutable_device_block, 0).await?;

        // Wait for it to be processed.
        // TODO: This is a bit of a hack, and may lead to non-deterministic behavior.
        // In theory, the offload + memcpy should take much less time than this.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // Check that the block exists in the host pool
        let host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
985
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
986
987
988
989
            .await?;

        assert_eq!(host_blocks.len(), 1);
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
990
991
            host_blocks[0].sequence_hash(),
            immutable_device_block.sequence_hash()
992
993
        );

994
        check_block_contents(&immutable_device_block, &host_blocks[0], 42)?;
995
996
997
998
999
1000

        Ok(())
    }

    #[tokio::test]
    async fn test_no_host_blocks_available() -> Result<()> {
1001
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;
1002

1003
1004
        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023

        let host_blocks = host_pool.allocate_blocks(4).await?;
        assert_eq!(host_blocks.len(), 4);

        let device_block = completed_block(device_pool, [0, 1, 2, 3]).await?;
        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

        offload_manager.offload(&immutable_device_block, 0).await?;

        // Wait for offload to be processed.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // The offload should fail gracefuly due to a lack of host blocks
        let matched_host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
1024
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
            .await?;
        assert_eq!(matched_host_blocks.len(), 0);

        // Wait for blocks to be returned to the pool.
        drop(host_blocks);
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // Try the offload again.
        offload_manager.offload(&immutable_device_block, 0).await?;

        // Wait for offload to be processed.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // This time, the offload should succeed.
        let matched_host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
1040
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1041
1042
1043
1044
1045
1046
1047
            .await?;
        assert_eq!(matched_host_blocks.len(), 1);

        Ok(())
    }

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_onboard(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools_with_layout(
            4,
            Some(4),
            None,
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
1061

1062
1063
        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073

        // Allocate and fill a block on the host.
        let host_block = completed_block(host_pool, [0, 1, 2, 3]).await?;
        let immutable_host_block = host_pool
            .register_blocks(vec![host_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

1074
        populate_block(&immutable_host_block, 42)?;
1075
1076
1077

        // Onboard the block.
        let onboarded_blocks = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1078
1079
            .onboard(vec![immutable_host_block.clone()], None)
            .await??;
1080
1081
1082
1083

        assert_eq!(onboarded_blocks.len(), 1);
        // Check that the sequence hash is the same.
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1084
1085
            onboarded_blocks[0].sequence_hash(),
            immutable_host_block.sequence_hash()
1086
1087
1088
1089
        );
        // Check that the block is registered.
        assert!(matches!(
            onboarded_blocks[0].state(),
1090
            BlockState::Registered(_, _)
1091
1092
        ));

1093
        check_block_contents(&immutable_host_block, &onboarded_blocks[0], 42)?;
1094
1095
1096
1097

        // Wait for the new value to show up in the device pool.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        let device_blocks = device_pool
Ryan Olson's avatar
Ryan Olson committed
1098
            .match_sequence_hashes(vec![onboarded_blocks[0].sequence_hash()].as_slice())
1099
1100
1101
            .await?;
        assert_eq!(device_blocks.len(), 1);
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1102
1103
            device_blocks[0].sequence_hash(),
            onboarded_blocks[0].sequence_hash()
1104
1105
1106
        );

        // Check that this is the same block.
1107
        check_block_contents(&immutable_host_block, &device_blocks[0], 42)?;
1108
1109
1110
1111
1112

        Ok(())
    }

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_offload_onboard(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools_with_layout(
            4,
            Some(4),
            None,
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
1126

1127
1128
        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
1129
1130
1131
1132
1133
1134
1135
1136
1137

        let device_block = completed_block(device_pool, [0, 1, 2, 3]).await?;
        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

1138
        populate_block(&immutable_device_block, 42)?;
1139
1140
1141
1142
1143
1144
1145
1146
        // Offload the block to the host.
        offload_manager.offload(&immutable_device_block, 0).await?;

        // Wait for the offload to be processed.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // Check that the block exists in the host pool.
        let immutable_host_block = host_pool
Ryan Olson's avatar
Ryan Olson committed
1147
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1148
1149
1150
1151
1152
            .await?
            .into_iter()
            .next()
            .unwrap();

1153
        check_block_contents(&immutable_device_block, &immutable_host_block, 42)?;
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168

        // Remove the device block from the pool by dropping it and allocating more blocks.
        drop(immutable_device_block);

        // Wait for the block to be returned to the pool.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let device_blocks = device_pool.allocate_blocks(4).await?;
        assert_eq!(device_blocks.len(), 4);

        drop(device_blocks);
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // Check that the block is not in the device pool.
        let device_blocks = device_pool
Ryan Olson's avatar
Ryan Olson committed
1169
            .match_sequence_hashes(vec![immutable_host_block.sequence_hash()].as_slice())
1170
1171
1172
1173
1174
            .await?;
        assert_eq!(device_blocks.len(), 0);

        // Onboard the block back to the device pool.
        let onboarded_blocks = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1175
1176
            .onboard(vec![immutable_host_block.clone()], None)
            .await??;
1177
1178
        assert_eq!(onboarded_blocks.len(), 1);
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1179
1180
            onboarded_blocks[0].sequence_hash(),
            immutable_host_block.sequence_hash()
1181
1182
1183
        );
        assert!(matches!(
            onboarded_blocks[0].state(),
1184
            BlockState::Registered(_, _)
1185
1186
        ));

1187
        check_block_contents(&immutable_host_block, &onboarded_blocks[0], 42)?;
1188
1189
1190
1191
1192
1193

        Ok(())
    }

    #[tokio::test]
    async fn test_onboard_err_handling() -> Result<()> {
1194
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;
1195

1196
1197
        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210

        let host_block = completed_block(host_pool, [0, 1, 2, 3]).await?;
        let immutable_host_block = host_pool
            .register_blocks(vec![host_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

        let device_blocks = device_pool.allocate_blocks(4).await?;
        assert_eq!(device_blocks.len(), 4);

        let res = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1211
1212
            .onboard(vec![immutable_host_block.clone()], None)
            .await?;
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
        assert!(matches!(
            res.err().unwrap(),
            BlockPoolError::NotEnoughBlocksAvailable(_, _)
        ));

        Ok(())
    }

    #[tokio::test]
    async fn test_offload_onboard_no_host_blocks() -> Result<()> {
1223
        let (offload_manager, device_pool, _, _) = build_pools(4, None, None, None)?;
1224

1225
        let device_pool = device_pool.as_ref().unwrap();
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238

        let device_block = completed_block(device_pool, [0, 1, 2, 3]).await?;
        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

        offload_manager.offload(&immutable_device_block, 0).await?;

        Ok(())
    }
1239
1240

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_offload_disk(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, _, host_pool, disk_pool) = build_pools_with_layout(
            4,
            Some(4),
            Some(4),
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
1254

1255
1256
        let host_pool = host_pool.as_ref().unwrap();
        let disk_pool = disk_pool.as_ref().unwrap();
1257
1258
1259
1260
1261
1262
1263
1264
1265

        let host_block = completed_block(host_pool, [0, 1, 2, 3]).await?;
        let immutable_host_block = host_pool
            .register_blocks(vec![host_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

1266
        populate_block(&immutable_host_block, 42)?;
1267
1268
1269
1270
1271
1272

        offload_manager.offload(&immutable_host_block, 0).await?;

        tokio::time::sleep(std::time::Duration::from_millis(500)).await;

        let disk_blocks = disk_pool
Ryan Olson's avatar
Ryan Olson committed
1273
            .match_sequence_hashes(vec![immutable_host_block.sequence_hash()].as_slice())
1274
1275
1276
            .await?;
        assert_eq!(disk_blocks.len(), 1);
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1277
1278
            disk_blocks[0].sequence_hash(),
            immutable_host_block.sequence_hash()
1279
1280
        );

1281
        check_block_contents(&immutable_host_block, &disk_blocks[0], 42)?;
1282
1283
1284
1285
1286

        Ok(())
    }

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_onboard_disk(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, device_pool, _, disk_pool) = build_pools_with_layout(
            4,
            None,
            Some(4),
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
1300

1301
1302
        let device_pool = device_pool.as_ref().unwrap();
        let disk_pool = disk_pool.as_ref().unwrap();
1303
1304
1305
1306
1307
1308
1309
1310
1311

        let disk_block = completed_block(disk_pool, [0, 1, 2, 3]).await?;
        let immutable_disk_block = disk_pool
            .register_blocks(vec![disk_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

1312
1313
        populate_block(&immutable_disk_block, 42)?;

1314
        let device_block = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1315
1316
            .onboard(vec![immutable_disk_block.clone()], None)
            .await??;
1317

1318
1319
        check_block_contents(&immutable_disk_block, &device_block[0], 42)?;

1320
1321
        assert_eq!(device_block.len(), 1);
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1322
1323
            device_block[0].sequence_hash(),
            immutable_disk_block.sequence_hash()
1324
1325
1326
        );
        assert_eq!(
            device_pool
Ryan Olson's avatar
Ryan Olson committed
1327
                .match_sequence_hashes(vec![immutable_disk_block.sequence_hash()].as_slice())
1328
1329
1330
1331
1332
1333
1334
1335
1336
                .await?
                .len(),
            1
        );

        Ok(())
    }

    #[tokio::test]
Ryan Olson's avatar
Ryan Olson committed
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
    #[rstest]
    #[case(LayoutType::FullyContiguous)]
    #[case(LayoutType::LayerSeparate { outer_contiguous: true })]
    #[case(LayoutType::LayerSeparate { outer_contiguous: false })]
    async fn test_bulk_transfer_disk(#[case] layout_type: LayoutType) -> Result<()> {
        let (offload_manager, device_pool, host_pool, disk_pool) = build_pools_with_layout(
            8,
            Some(8),
            Some(8),
            None,
            layout_type,
            BlockRegistrationDuplicationSetting::Disabled,
        )?;
1350

1351
1352
1353
        let disk_pool = disk_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
        let device_pool = device_pool.as_ref().unwrap();
1354
1355
1356
1357
1358

        let mut host_blocks = Vec::new();

        for i in 0..8 {
            let block = completed_block(host_pool, [i; 4]).await?;
1359
            populate_block(&block, i as u8)?;
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
            host_blocks.push(block);
        }

        let immutable_host_blocks = host_pool.register_blocks(host_blocks).await?;

        for block in &immutable_host_blocks {
            offload_manager.offload(block, 0).await?;
        }

        tokio::time::sleep(std::time::Duration::from_millis(500)).await;

        let mut disk_blocks = Vec::new();

1373
        for (i, host_block) in immutable_host_blocks.iter().enumerate() {
1374
            let blocks = disk_pool
Ryan Olson's avatar
Ryan Olson committed
1375
                .match_sequence_hashes(vec![host_block.sequence_hash()].as_slice())
1376
1377
                .await?;
            assert_eq!(blocks.len(), 1);
1378
            check_block_contents(host_block, &blocks[0], i as u8)?;
1379
1380
1381
            disk_blocks.push(blocks[0].clone());
        }

Ryan Olson's avatar
Ryan Olson committed
1382
        let device_blocks = offload_manager.onboard(disk_blocks.clone(), None).await??;
1383
1384
        assert_eq!(device_blocks.len(), disk_blocks.len());

1385
        for (i, disk_block) in disk_blocks.iter().enumerate() {
1386
            let blocks = device_pool
Ryan Olson's avatar
Ryan Olson committed
1387
                .match_sequence_hashes(vec![disk_block.sequence_hash()].as_slice())
1388
1389
                .await?;
            assert_eq!(blocks.len(), 1);
1390
            check_block_contents(disk_block, &blocks[0], i as u8)?;
1391
1392
1393
1394
        }

        Ok(())
    }
1395
1396
1397
1398
1399
1400
1401

    #[tokio::test]
    async fn test_transfer_batcher() -> Result<()> {
        let (offload_manager, device_pool, _, disk_pool) = build_pools(
            2 * MAX_TRANSFER_BATCH_SIZE + 1,
            None,
            Some(2 * MAX_TRANSFER_BATCH_SIZE + 1),
1402
            None,
1403
1404
1405
1406
1407
1408
1409
1410
        )?;

        let device_pool = device_pool.as_ref().unwrap();
        let disk_pool = disk_pool.as_ref().unwrap();

        let mut disk_blocks = Vec::new();

        for i in 0..2 * MAX_TRANSFER_BATCH_SIZE + 1 {
1411
1412
1413
            let disk_block = completed_block(disk_pool, [i as u32; 4]).await?;
            populate_block(&disk_block, i as u8)?;
            disk_blocks.push(disk_block);
1414
1415
1416
1417
1418
        }

        let immutable_disk_blocks = disk_pool.register_blocks(disk_blocks).await?;

        let device_blocks = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1419
1420
            .onboard(immutable_disk_blocks.clone(), None)
            .await??;
1421
1422
        assert_eq!(device_blocks.len(), 2 * MAX_TRANSFER_BATCH_SIZE + 1);

1423
        for (i, device_block) in device_blocks.iter().enumerate() {
1424
            let blocks = device_pool
Ryan Olson's avatar
Ryan Olson committed
1425
                .match_sequence_hashes(vec![device_block.sequence_hash()].as_slice())
1426
                .await?;
1427
            check_block_contents(device_block, &blocks[0], i as u8)?;
1428
1429
1430
1431
1432
            assert_eq!(blocks.len(), 1);
        }

        Ok(())
    }
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448

    #[tokio::test]
    async fn test_onboard_unsupported_block_type() -> Result<()> {
        let (offload_manager, device_pool, _, _) = build_pools(1, None, None, None)?;

        let device_pool = device_pool.as_ref().unwrap();

        let block = completed_block(device_pool, [0; 4]).await?;

        let registered_block = device_pool
            .register_blocks(vec![block])
            .await?
            .into_iter()
            .next()
            .unwrap();

Ryan Olson's avatar
Ryan Olson committed
1449
1450
1451
        let onboarded_blocks = offload_manager
            .onboard(vec![registered_block], None)
            .await?;
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
        assert!(matches!(
            onboarded_blocks,
            Err(BlockPoolError::BlockError(BlockError::Other(_)))
        ));

        Ok(())
    }

    #[tokio::test]
    async fn test_offload_transfer_metadata() -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;

        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();

        let mut device_block = completed_block(device_pool, [0; 4]).await?;

        populate_block(&device_block, 42)?;

        let new_metadata = device_block.metadata().update_priority(1);
        device_block.update_metadata(new_metadata);

        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();
        offload_manager.offload(&immutable_device_block, 0).await?;

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
1485
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
            .await?;
        assert_eq!(host_blocks.len(), 1);
        check_block_contents(&immutable_device_block, &host_blocks[0], 42)?;
        assert_eq!(host_blocks[0].metadata().priority(), 1);

        Ok(())
    }

    #[tokio::test]
    async fn test_onboard_duplicate() -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;

        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();

        let device_block = completed_block(device_pool, [0; 4]).await?;

        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

        populate_block(&immutable_device_block, 42)?;

        offload_manager.offload(&immutable_device_block, 0).await?;

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
1517
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1518
1519
1520
1521
            .await?;
        assert_eq!(host_blocks.len(), 1);

        let onboarded_blocks = offload_manager
Ryan Olson's avatar
Ryan Olson committed
1522
1523
            .onboard(vec![host_blocks[0].clone()], None)
            .await??;
1524
1525
1526
1527
1528
1529
        assert_eq!(onboarded_blocks.len(), 1);
        check_block_contents(&host_blocks[0], &onboarded_blocks[0], 42)?;

        // This should be the same block that we put on the device.
        // The block that was copied should be discarded by the block pool.
        assert_eq!(
Ryan Olson's avatar
Ryan Olson committed
1530
1531
            onboarded_blocks[0].block_id(),
            immutable_device_block.block_id()
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
        );

        Ok(())
    }

    #[tokio::test]
    async fn test_transfer_big_blocks() -> Result<()> {
        // Try a block size of 32 MB.
        let inner_dim = 2_usize.pow(20) * 32 / NUM_LAYERS / BLOCK_SIZE;
        let (offload_manager, device_pool, host_pool, disk_pool) =
            build_pools(2, Some(2), Some(2), Some(inner_dim))?;

        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();
        let disk_pool = disk_pool.as_ref().unwrap();

        let device_block = completed_block(device_pool, [0; 4]).await?;

        populate_block(&device_block, 42)?;

        let immutable_device_block = device_pool
            .register_blocks(vec![device_block])
            .await?
            .into_iter()
            .next()
            .unwrap();

        // Offload to host.
        offload_manager.offload(&immutable_device_block, 0).await?;

        // Wait for the offload to be processed.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let host_blocks = host_pool
Ryan Olson's avatar
Ryan Olson committed
1566
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
            .await?;
        assert_eq!(host_blocks.len(), 1);
        check_block_contents(&immutable_device_block, &host_blocks[0], 42)?;

        // Offload to disk
        offload_manager.offload(&host_blocks[0], 0).await?;

        // Wait for the offload to be processed.
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;

        let disk_blocks = disk_pool
Ryan Olson's avatar
Ryan Olson committed
1578
            .match_sequence_hashes(vec![immutable_device_block.sequence_hash()].as_slice())
1579
1580
1581
1582
1583
            .await?;
        assert_eq!(disk_blocks.len(), 1);
        check_block_contents(&host_blocks[0], &disk_blocks[0], 42)?;

        // Onboard to device.
Ryan Olson's avatar
Ryan Olson committed
1584
        let device_blocks = offload_manager.onboard(disk_blocks.clone(), None).await??;
1585
1586
1587
1588
1589
        assert_eq!(device_blocks.len(), 1);
        check_block_contents(&disk_blocks[0], &device_blocks[0], 42)?;

        Ok(())
    }
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626

    #[tokio::test]
    async fn test_offload_evict_order() -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;

        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();

        let tokens = vec![0_u32; BLOCK_SIZE * 4];
        let token_blocks = TokenBlockSequence::new(Tokens::from(tokens), 4, None);
        assert_eq!(token_blocks.blocks().len(), 4);

        let mut mutable_blocks = Vec::new();
        let mut sequence_hashes = Vec::new();
        for token_block in token_blocks.blocks() {
            let mut mutable_block = device_pool
                .allocate_blocks(1)
                .await?
                .into_iter()
                .next()
                .unwrap();
            mutable_block.apply_token_block(token_block.clone())?;
            sequence_hashes.push(mutable_block.sequence_hash()?);
            mutable_blocks.push(mutable_block);
        }

        let immutable_blocks = device_pool.register_blocks(mutable_blocks).await?;

        for block in &immutable_blocks {
            offload_manager.offload(block, 0).await?;
        }
        // Wait for offloads.
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        // Allocate 2 blocks on the host.
        let _host_blocks = host_pool.allocate_blocks(2).await?;

Ryan Olson's avatar
Ryan Olson committed
1627
1628
        // The first two blocks should've been evicted.
        // The last two blocks should still be on the host.
1629
1630
1631
1632
1633
        assert_eq!(
            host_pool
                .match_sequence_hashes(sequence_hashes.as_slice())
                .await?
                .len(),
Ryan Olson's avatar
Ryan Olson committed
1634
            0
1635
1636
1637
1638
        );

        assert_eq!(
            host_pool
Ryan Olson's avatar
Ryan Olson committed
1639
                .match_sequence_hashes(&sequence_hashes[2..])
1640
1641
                .await?
                .len(),
Ryan Olson's avatar
Ryan Olson committed
1642
            2
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
        );

        Ok(())
    }

    #[tokio::test]
    async fn test_onboard_evict_order() -> Result<()> {
        let (offload_manager, device_pool, host_pool, _) = build_pools(4, Some(4), None, None)?;

        let device_pool = device_pool.as_ref().unwrap();
        let host_pool = host_pool.as_ref().unwrap();

        let tokens = vec![0_u32; BLOCK_SIZE * 4];
        let token_blocks = TokenBlockSequence::new(Tokens::from(tokens), 4, None);
        assert_eq!(token_blocks.blocks().len(), 4);

        let mut mutable_blocks = Vec::new();
        let mut sequence_hashes = Vec::new();
        for token_block in token_blocks.blocks() {
            let mut block = host_pool
                .allocate_blocks(1)
                .await?
                .into_iter()
                .next()
                .unwrap();
            block.apply_token_block(token_block.clone())?;

            sequence_hashes.push(block.sequence_hash()?);
            mutable_blocks.push(block);
        }

        let immutable_blocks = host_pool.register_blocks(mutable_blocks).await?;

Ryan Olson's avatar
Ryan Olson committed
1676
        let _ = offload_manager.onboard(immutable_blocks, None).await?;
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let _device_blocks = device_pool.allocate_blocks(2).await?;

        assert_eq!(
            device_pool
                .match_sequence_hashes(sequence_hashes.as_slice())
                .await?
                .len(),
            2
        );

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

        let _device_blocks2 = device_pool.allocate_blocks(1).await?;

        assert_eq!(
            device_pool
                .match_sequence_hashes(sequence_hashes.as_slice())
                .await?
                .len(),
            1
        );

        Ok(())
    }
1704
}