Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -614,13 +614,17 @@ async def _download_ranges_on_stream(
and offset == 0
and length == self.persisted_size
)
wrapped_buffer = _wrap_user_buffer(
user_buffer, length, accepts_memoryview
)
download_states[read_id] = _DownloadState(
initial_offset=offset,
initial_length=length,
user_buffer=_wrap_user_buffer(
user_buffer, length, accepts_memoryview
),
user_buffer=wrapped_buffer,
is_full_object_read=is_full_object_read,
# Unwrapped only for a write() destination that accepts
# memoryview chunks.
receives_views=wrapped_buffer is user_buffer,
)

initial_state = {
Expand Down Expand Up @@ -824,13 +828,17 @@ async def download_ranges(

:type enable_checksum: bool
:param enable_checksum: (Optional) If True, checksums are verified for downloaded data. Defaults to True.
Chunks of ``GCS_PYTHON_CLIENT_CRC32C_OFFLOAD_MIN_BYTES`` bytes or
more (default 1 MiB) are verified on a worker thread and written to
their buffer once the checksum matches; chunks still waiting are
discarded if the call is cancelled or a mismatch is found, and a
retry requests them again. Setting
``GCS_PYTHON_CLIENT_CRC32C_OFFLOAD_MIN_BYTES=0`` verifies every
chunk inline.
By default, chunks of 1 MiB or more that a ``write()`` destination
receives as ``memoryview`` are verified on a worker thread and
written once their checksum matches. Destinations receive
``memoryview`` chunks with ``accepts_memoryview=True``, the
zero-copy parser and a ``google-crc32c`` that accepts
``memoryview``. On cancellation or a mismatch, waiting chunks are
not written. Other chunks, and all chunks in ranges that read the
whole object, are verified as they arrive.
``GCS_PYTHON_CLIENT_CRC32C_OFFLOAD=1`` (or ``true``, ``yes``,
``on``) offloads every chunk of 1 MiB or more outside whole-object
ranges, and any other non-empty value keeps every chunk inline.

:type accepts_memoryview: bool
:param accepts_memoryview: (Optional) If True, ``write()`` destinations
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,29 +36,32 @@
logger = logging.getLogger(__name__)


def _int_from_env(name: str, default: int) -> int:
"""Reads an integer tuning knob from the environment; bad values are ignored."""
try:
return int(os.environ.get(name, default))
except ValueError:
return default


# Chunks at least this large are checksummed on a worker thread instead of the
# event-loop thread; smaller chunks are hashed inline, and 0 (or any value
# below 1) hashes every chunk inline. The 1 MiB default matches google_crc32c's
# GIL-release threshold, so offloaded hashes over ``bytes``-backed chunks
# (received chunks are) always run with the GIL released.
_CRC32C_OFFLOAD_MIN_BYTES = _int_from_env(
"GCS_PYTHON_CLIENT_CRC32C_OFFLOAD_MIN_BYTES",
getattr(google_crc32c, "GIL_RELEASE_THRESHOLD", 1024 * 1024),
)
# Chunks of at least _CRC32C_OFFLOAD_MIN_BYTES can be checksummed on a worker
# thread instead of the event-loop thread. That helps when the loop thread is
# the bottleneck and no ``bytes`` copy of each chunk is left on it, so by
# default only chunks that reach their destination as a ``memoryview`` are
# offloaded (see _DownloadState.receives_views).
# GCS_PYTHON_CLIENT_CRC32C_OFFLOAD overrides that: ``1`` (or ``true``, ``yes``,
# ``on``) offloads every such chunk, and any other non-empty value none. The
# threshold matches google_crc32c's GIL-release threshold: smaller chunks would
# hold the GIL on the worker, so they are always hashed inline.
_CRC32C_OFFLOAD_ENV_VAR = "GCS_PYTHON_CLIENT_CRC32C_OFFLOAD"
_CRC32C_OFFLOAD_ENABLED_VALUES = ("1", "true", "yes", "on")
_CRC32C_OFFLOAD_MIN_BYTES = getattr(google_crc32c, "GIL_RELEASE_THRESHOLD", 1024 * 1024)
# Upper bound on chunks held for verification per download_ranges() call.
# Chunks are written only once their checksum matches, so this keeps a slow
# worker from pinning an unbounded number of received messages.
_CRC32C_MAX_PENDING = 32


def _should_offload_crc32c(read_state: "_DownloadState", data: Any) -> bool:
"""Whether to verify a large chunk on the worker pool instead of inline."""
value = os.environ.get(_CRC32C_OFFLOAD_ENV_VAR, "").strip().lower()
if value:
return value in _CRC32C_OFFLOAD_ENABLED_VALUES
return read_state.receives_views and isinstance(data, memoryview)


def _new_crc32c_executor() -> concurrent.futures.ThreadPoolExecutor:
return concurrent.futures.ThreadPoolExecutor(
max_workers=2, thread_name_prefix="gcs-crc32c"
Expand Down Expand Up @@ -111,10 +114,14 @@ def __init__(
user_buffer: IO[bytes],
is_full_object_read: bool = False,
enable_checksum: bool = True,
receives_views: bool = False,
):
self.initial_offset = initial_offset
self.initial_length = initial_length
self.user_buffer = user_buffer
# Whether user_buffer takes chunks as received, so a memoryview chunk
# reaches it without a bytes copy on the event-loop thread.
self.receives_views = receives_views
self.bytes_written = 0
# Offset of the next chunk to accept. Runs ahead of
# initial_offset + bytes_written while received chunks are held for
Expand Down Expand Up @@ -214,9 +221,9 @@ def update_state_from_response(
if checksum_enabled and checksummed_data.HasField("crc32c"):
server_checksum = checksummed_data.crc32c
if (
_CRC32C_OFFLOAD_MIN_BYTES > 0
and len(data) >= _CRC32C_OFFLOAD_MIN_BYTES
len(data) >= _CRC32C_OFFLOAD_MIN_BYTES
and read_state.rolling_checksum is None
and _should_offload_crc32c(read_state, data)
):
# Hash off the loop thread; the chunk is written by
# verify_pending_checksums() once the checksum matches.
Expand Down
2 changes: 2 additions & 0 deletions packages/google-cloud-storage/tests/system/test_rapid.py
Original file line number Diff line number Diff line change
Expand Up @@ -1594,6 +1594,8 @@ def test_mrd_zero_copy_bidi_read(
):
"""Tests zero-copy BidiReadObject reads across write() and buffer destinations."""
monkeypatch.setenv("GCS_PYTHON_CLIENT_ZERO_COPY_BIDI_READ", "1")
# Partial ranges below have 2 MiB chunks, so this also covers off-loop CRC32C.
monkeypatch.setenv("GCS_PYTHON_CLIENT_CRC32C_OFFLOAD", "1")
object_size = 5 * 1024 * 1024
object_name = f"test_mrd_zero_copy-{uuid.uuid4()}"

Expand Down
Loading
Loading