Cataly...stMmap(3pm)

💖 Catalyst::Plugin::Session::Store::FastMmap 💖

okay bestie, gather round, because this one is a Perl module and it's User Contributed Perl Documentation, so it lives in section 3pm of your manual pages. Yes, the whole name is a mouthful, we know — it's Catalyst::Plugin::Session::Store::FastMmap and honestly the name alone is doing cardio. But it's giving fast session storage and we're gonna stan. 🫶

---

✨ NAME ✨

Catalyst::Plugin::Session::Store::FastMmap — the fast session storage backend, bestie. It stores your sessions, it does it fast, and that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

here's how you actually use it, no cap:

use Catalyst qw/Session Session::Store::FastMmap Session::State::Foo/;

MyApp->config(
    'Plugin::Session' => {
        expires => 3600,
        storage => '/tmp/session'
    },
);

# ... in an action:
$c->session->{foo} = 'bar'; # will be saved

see that last line? you just drop stuff into $c->session->{foo} and it literally gets saved. iconic behaviour, no notes. 🎀

---

🦋 DESCRIPTION 🦋

Catalyst::Plugin::Session::Store::FastMmap is a fast session storage plugin for Catalyst that uses an mmap'ed file to act as a shared memory interprocess cache. She's based on Cache::FastMmap, and yes she's fast, it's in the name, we've been over this. ⭐

💜 METHODS 💜

• get_session_data
• store_session_data
• delete_session_data
• delete_expired_sessions

These four are the implementations of the required methods for a store. Wanna know the tea? Go read Catalyst::Plugin::Session::Store. 📖

• get_and_set_session_data

This is the optional method for atomic write semantics. See Catalyst::Plugin::Session::AtomicWrite for the details, iykyk. 🔥

• setup_session

Sets up the session cache file. That's the whole job. She's doing great. 👑

---

💀 CAVEATS 💀

okay so this is the part where we get real, because there are some actual dangers here and I need you to lock in. 🚨

Very loaded sites with lots of data in the session hash may have old sessions expired prematurely, due to the LRU caching policy employed by Cache::FastMmap. To get around this you can increase the "cache_size" parameter, or switch session storage backends. And btw, Cache::FastMmap defaults to around 5mb (89 * 64k) — so yeah, that's the starting point, plan accordingly bestie.

This is particularly inappropriate for use as a backend for e.g. Catalyst::Plugin::Session::PerUser, for example. Just don't do it. I'm begging. 🙈

As Cache::FastMmap is not "thread-safe" (at least version 1.30 and before) therefore also this module does not work in multi-threaded environment. It is "fork-safe", however keep in mind that on Win32 the perl fork call is implemented as an emulation via threads — that is the reason why you cannot use this store for example when running you catalyst application on Win32 platform with Catalyst::Engine::HTTP::Prefork engine.

fr fr: multi-threaded = nope. Win32 + Catalyst::Engine::HTTP::Prefork = also nope. this is not a drill. 😭

---

🌈 CONFIGURATION 🌈

These parameters are placed in the hash under the "Plugin::Session" key in the configuration hash. So like, that's where they live. That's their home. 🏠

• storage — Specifies the file to be used for the sharing of session data. The default value will use File::Spec to find the default tempdir, and use a file named "MyApp_session_data", where "MyApp" is replaced with the appname.

Important heads up: the file will be created with mode 0640, which means that it will only be writeable by processes running with the same uid as the process that creates the file. If this may be a problem, for example if you may try to debug the program as one user and run it as another, specify a filename like "/tmp/session-$>", which includes the UID of the process in the filename. sneaky but slay. 💅

• init_file
• cache_size
• unlink_on_exit

See the Cache::FastMmap documentation for the meaning of these keys. If these keys are not present, Cache::FastMmap's defaults will be used. Simple as that. ✨

---

👀 SEE ALSO 👀

• Catalyst
• Catalyst::Plugin::Session
• Cache::FastMmap

go read them, they're the supporting cast and they ate. 🍓

---

🫶 AUTHORS 🫶

This module is derived from Catalyst::Plugin::Session::FastMmap code, and has been heavily modified since. The way that this list of legends carried this whole thing… 😭

 Andrew Ford
 Andy Grundman
 Christian Hansen
 Yuval Kogman, <nothingmuch@woobling.org>
 Marcus Ramberg
 Sebastian Riedel
 Tomas Doran, (t0m) <bobtfish@bobtfish.net>

---

🎀 COPYRIGHT 🎀

Copyright (c) 2005 - 2012 the Catalyst::Plugin::Session::Store::FastMmap "AUTHORS" as listed above.

---

💖 LICENSE 💖

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. periodt. 👑

---

and that's the whole page bestie!! this was perl v5.34.0, dated 2022-06-09, from the Catalyst::Plugin::Session::Store::FastMmap manual in section 3pm — thanks for reading, mwah, go forth and store your sessions fast. 💜🦋🌸