MongoD...dStream(3pm)

💖 MongoDB::GridFSBucket::DownloadStream — bestie edition 💖

okay so this is a page from the User Contributed Perl Documentation (the 3pm kind, iykyk), and it's literally all about downloading files. let's get into it 🦋

---

✨ NAME ✨

MongoDB::GridFSBucket::DownloadStream — it's giving file handle abstraction for downloading. that's the whole vibe. 💅

🌸 VERSION 🌸

version v2.2.2 — yes bestie, that's the current one, no cap.

✨ SYNOPSIS ✨

here's how you actually use it, two ways, pick your fighter:

# OO API
$stream = $bucket->open_download_stream($file_id)
while ( my $line = $stream->readline ) {
    ...
}

# Tied-handle API
$fh = $stream->fh;
while ( my $line = <$fh> ) {
    ...
}

🎀 DESCRIPTION 🎀

so this class is a file abstraction for downloading. you stream data out of an object of this class either by calling methods on it or through a tied-handle interface. both slay, both valid. 🫶

👑 ATTRIBUTES 👑

file_doc

the file document for the file you're downloading. that's it, that's the attribute. 💜

valid file documents typically include the following fields, and the way that a "typically" is doing so much heavy lifting here — legacy stuff exists, be nice to it:

• _id — a unique ID for this document, typically a BSON::OID object. legacy GridFS files may store this value as a different type, so don't assume bestie.
• length — the length of this stored file, in bytes.
• chunkSize — the size, in bytes, of each full data chunk of this file.
• uploadDate — the date and time this file was added to GridFS, stored as a BSON datetime value and inflated per the bucket's bson_codec attribute.
• filename — the name of this stored file; this does not need to be unique. two files, same name, coexisting peacefully, periodt.
• metadata — any additional application-specific data, your lil extras, go off.
• md5 — DEPRECATED 💀
• contentType — DEPRECATED 💀
• aliases — DEPRECATED 💀

---

🔥 METHODS 🔥

fh

my $fh = $downloadstream->fh;
while ( <$fh> ) {
    say($_);
}

returns a new Perl file handle tied to this instance of DownloadStream. you can operate on it with the built-in functions read, readline, getc, eof, fileno and close. iconic behavior ngl. ✨

important notes, and bestie please read these ones:

letting one of these tied filehandles fall out of scope will NOT cause close to be called. this is due to the way tied file handles are implemented in Perl — not my rules, blame the language. 😭 for close to be called implicitly, all tied filehandles and the original object must go out of scope. all of them. every single one.

each file handle retrieved this way is tied back to the same object, so calling close on multiple tied file handles and/or the original object will have the same effect as calling close on the original object multiple times. it's giving one collective soul fr fr. 💫

close

$stream->close

works like the builtin close. simple. clean. 🌈

important notes:

• calling close will also cause any tied file handles created for the stream to also close. they go down together. 😭
• close will be automatically called when a stream object is destroyed. so like, it handles itself, main character energy.
• calling close repeatedly will warn. so don't spam it, bestie, it will literally tell on you. 💀

eof

if ( $stream->eof() ) { ... }

works like the builtin eof. are we at the end? vibe check. ✨

fileno

if ( $stream->fileno() ) { ... }

works like the builtin fileno, but it returns -1 if the stream is open and undef if it's closed. yes, -1 and undef, two different things, don't mix them up. 🫶

getc

$char = $stream->getc();

works like the builtin getc. one little guy at a time. 🍓

read

$data = $stream->read($buf, $length, $offset)

works like the builtin read. 🦋

readline

$line  = $stream->readline();
@lines = $stream->readline();

works like the builtin readline. scalar context, list context, both eat. 👑

---

💜 AUTHORS 💜

the legends who made this happen, show some respect:

• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>

🎀 COPYRIGHT AND LICENSE 🎀

this software is Copyright (c) 2020 by MongoDB, Inc.

it's free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page bestie!! sign-off time: this was served up by perl v5.40.1, dated 2025-04-03, and it's the MongoD...dStream(3pm) page from the User Contributed Perl Documentation. go forth and stream responsibly 💖✨🌸🦋💅🫶