/ 
Linux-FD-Mem-0.002
River stage zero No dependents
/ Linux::FD::Mem

NAME

Linux::FD::Mem - memory file descriptors

VERSION

version 0.002

SYNOPSIS

use Linux::FD::Mem;

my $fh = Linux::FD::Mem->new('name', 'allow-seals');
... # write-map the file
$fh->seal('future-write', 'shrink', 'grow', 'write');

DESCRIPTION

Linux::FD::Mem provides memory file descriptors; these will not be represented on the file-system in any way. They can be made to use seals or larger page-sizes.

METHODS

new($name, @flags)

This creates an anonymous file and returns a file handle that refers to it. The file behaves like a regular file, and so can be modified, truncated, memory-mapped, and so on. However, unlike a regular file, it lives in RAM and has a volatile backing storage. Once all references to the file are dropped, it is automatically released. Anonymous memory is used for all backing pages of the file. Therefore, files created by this module have the same semantics as other anonymous memory allocations such as those allocated using File::Map's map_anonymous.

The name supplied in $name is used as a filename and will be displayed as the target of the corresponding symbolic link in the directory /proc/self/fd/. The displayed name is always prefixed with memfd: and serves only for debugging purposes. Names do not affect the behavior of the file descriptor, and as such multiple files can have the same name without any side effects.

@flags is an optional list of flags. It allows one of the following two values:

  • "allow-sealing"

    This is used to allow sealing the filehandle.

  • "huge-table"

    to allow huge table support. If "huge-table" is given one can also pass either "huge-2mb" or "huge-1gb" to explicitly set the page size.

seal(@flags)

This is used to add a seal to the filehandle. Allowed values are:

  • "seal"

    If this is set, no further seals can be added to the filehandle.

  • "shrink"

    If this is set the file in question cannot be reduced in size.

  • "grow"

    If this is set the size of the file in question cannot be increased.

  • "write"

    If this is set you cannot modify the contents of the file. Note that shrinking or growing the size of the file is still possible and allowed, thus this seal is normally used in combination with one of the other seals.

    Adding this seal will fail if any writable, shared mapping exists.

  • "future-write"

    This seal is similar to "write" but will allow modification via previously existing writable memory maps. It will not allow new such maps to be created.

    Using this seal one process can create a memory buffer that it can continue to modify while sharing that buffer on a read-only basis with other processes. This requires Linux 5.1.

get_seals()

This returns all the seals on the filehandle.

AUTHOR

Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.