[GH-ISSUE #861] [Usage]: Zero-copy usage questions #263

New issue

Closed

opened 2026-10-29 21:11:42 +00:00 by bsakaguchi · 3 comments

bsakaguchi commented

2026-10-29 21:11:42 +00:00

Owner

Originally created by @khuonglmhw on GitHub (Sep 18, 2025).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/861

Describe your usage question

Hello. I have some questions related to zero-copy.

import numpy as np
from mooncake.store import MooncakeDistributedStore

# Initialize store with RDMA protocol for maximum performance
store = MooncakeDistributedStore()
store.setup("localhost:12345", "http://localhost:8080/metadata", 512*1024*1024, 16*1024*1024, "tcp", "", "localhost:50051")

# Create data to store
original_data = np.random.randn(1000, 1000).astype(np.float32)
buffer_ptr = original_data.ctypes.data
size = original_data.nbytes

# Step 1: Register the buffer
result = store.register_buffer(buffer_ptr, size)
if result != 0:
    raise RuntimeError(f"Failed to register buffer: {result}")

# Step 2: Zero-copy store
result = store.put_from("large_tensor", buffer_ptr, size)
if result == 0:
    print(f"Successfully stored {size} bytes with zero-copy")
else:
    raise RuntimeError(f"Store failed with code: {result}")

# Step 3: Pre-allocate buffer for retrieval
retrieved_data = np.empty((1000, 1000), dtype=np.float32)
recv_buffer_ptr = retrieved_data.ctypes.data
recv_size = retrieved_data.nbytes

# Step 4: Register receive buffer
result = store.register_buffer(recv_buffer_ptr, recv_size)
if result != 0:
    raise RuntimeError(f"Failed to register receive buffer: {result}")

# Step 5: Zero-copy retrieval
bytes_read = store.get_into("large_tensor", recv_buffer_ptr, recv_size)
if bytes_read > 0:
    print(f"Successfully retrieved {bytes_read} bytes with zero-copy")
    # Verify the data
    print(f"Data matches: {np.array_equal(original_data, retrieved_data)}")
else:
    raise RuntimeError(f"Retrieval failed with code: {bytes_read}")

# Step 6: Clean up - unregister both buffers
store.unregister_buffer(buffer_ptr)
store.unregister_buffer(recv_buffer_ptr)
store.close()

Question 1: What happens when I unregister buffer_ptr just before step 3? Can I always retrieve the correct data with zerocopy? If I cannot retrieve data correctly, does the key still exist in the mooncake? (I tried and it returned correct data but I think it might be undefined behavior)

Question 2: If I set replica = 2, how does it work for zerocopy?

Question 3: Can I correctly get multiple time with zerocopy given that buffer for put is registered and pin (kept in memory) during that time?

Thank you.

Before submitting a new issue...

Make sure you already searched for relevant issues and read the documentation

Originally created by @khuonglmhw on GitHub (Sep 18, 2025). Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/861 ### Describe your usage question Hello. I have some questions related to zero-copy. ```python import numpy as np from mooncake.store import MooncakeDistributedStore # Initialize store with RDMA protocol for maximum performance store = MooncakeDistributedStore() store.setup("localhost:12345", "http://localhost:8080/metadata", 512*1024*1024, 16*1024*1024, "tcp", "", "localhost:50051") # Create data to store original_data = np.random.randn(1000, 1000).astype(np.float32) buffer_ptr = original_data.ctypes.data size = original_data.nbytes # Step 1: Register the buffer result = store.register_buffer(buffer_ptr, size) if result != 0: raise RuntimeError(f"Failed to register buffer: {result}") # Step 2: Zero-copy store result = store.put_from("large_tensor", buffer_ptr, size) if result == 0: print(f"Successfully stored {size} bytes with zero-copy") else: raise RuntimeError(f"Store failed with code: {result}") # Step 3: Pre-allocate buffer for retrieval retrieved_data = np.empty((1000, 1000), dtype=np.float32) recv_buffer_ptr = retrieved_data.ctypes.data recv_size = retrieved_data.nbytes # Step 4: Register receive buffer result = store.register_buffer(recv_buffer_ptr, recv_size) if result != 0: raise RuntimeError(f"Failed to register receive buffer: {result}") # Step 5: Zero-copy retrieval bytes_read = store.get_into("large_tensor", recv_buffer_ptr, recv_size) if bytes_read > 0: print(f"Successfully retrieved {bytes_read} bytes with zero-copy") # Verify the data print(f"Data matches: {np.array_equal(original_data, retrieved_data)}") else: raise RuntimeError(f"Retrieval failed with code: {bytes_read}") # Step 6: Clean up - unregister both buffers store.unregister_buffer(buffer_ptr) store.unregister_buffer(recv_buffer_ptr) store.close() ``` Question 1: What happens when I unregister buffer_ptr just before step 3? Can I always retrieve the correct data with zerocopy? If I cannot retrieve data correctly, does the key still exist in the mooncake? (I tried and it returned correct data but I think it might be undefined behavior) Question 2: If I set replica = 2, how does it work for zerocopy? Question 3: Can I correctly get multiple time with zerocopy given that buffer for put is registered and pin (kept in memory) during that time? Thank you. ### Before submitting a new issue... - [ ] Make sure you already searched for relevant issues and read the [documentation](https://kvcache-ai.github.io/Mooncake/)

bsakaguchi closed this issue

2026-10-29 21:11:42 +00:00

bsakaguchi commented

2026-10-29 21:11:43 +00:00

Author

Owner

@xiaguan commented on GitHub (Sep 18, 2025):

q1: In RDMA, the transfer might fail, but it could succeed over TCP.

q2: Replica isn’t related to zero-copy.

q3: Sure. You can register when the system starts up, and unregister when it shuts down. During that time, you’re free to use it.

@xiaguan commented on GitHub (Sep 18, 2025): q1: In RDMA, the transfer might fail, but it could succeed over TCP. q2: Replica isn’t related to zero-copy. q3: Sure. You can register when the system starts up, and unregister when it shuts down. During that time, you’re free to use it.

bsakaguchi commented

2026-10-29 21:11:43 +00:00

Author

Owner

@khuonglmhw commented on GitHub (Sep 18, 2025):

Thank you for your answer.

follow question 1, so for TCP, does it guarantee that as long as it is not evicted, I can still retrieve correct data with zerocopy?

@khuonglmhw commented on GitHub (Sep 18, 2025): Thank you for your answer. follow question 1, so for TCP, does it guarantee that as long as it is not evicted, I can still retrieve correct data with zerocopy?

bsakaguchi commented

2026-10-29 21:11:43 +00:00

Author

Owner

@xiaguan commented on GitHub (Sep 18, 2025):

not sure about this... you need to register for supporting more protocols (RDMA)

@xiaguan commented on GitHub (Sep 18, 2025): not sure about this... you need to register for supporting more protocols (RDMA)

bsakaguchi referenced this issue

2026-10-29 21:27:25 +00:00

[PR #263] [MERGED] Bump golang.org/x/net from 0.36.0 to 0.38.0 in /mooncake-transfer-engine/example/http-metadata-server #1436