pcma - Page Cache My Assets
pcma(5) provides a network protocol, server and reference client to warm up
the page cache and avoid page cache eviction.
-
Protocol based on ØMQ and MessagePack.
-
Single-threaded C server. See
pcmad(1). -
Single-threaded, single request C client. See
pcmac(1). -
Trivial test client providing an example Ruby implementation,
test/suite.rb. -
Files are locked using
mmap(2)andmlock(2). -
Locking only affects the beginning of the file, up to the size observed when locking. Files can be re-locked if needed.
If you do not fully understand the implications of locking pages in your operating system’s virtual memory, please don’t use this project.
I will not be held responsible for your poor memory management decisions.
pcma(5) is a dangerous tool, you could hurt your systems badly.
Furthermore, the provided Upstart and systemd scripts tune the OOM killer
never to kill pcmad(1).
Under memory pressure, even critical services might go down first.
This is the expected behaviour for our use case, but you might want to change
this.
Note that even if the memory will be completely locked in RAM, it will appear as
cached under GNU/Linux’s free.
Communications between the client and server are based on the request-reply model.
Both requests and replies are MessagePack arrays. As MessagePack is a binary protocol, we will use the equivalent JSON for readability.
The first item of every request is the command name.
The first item of every reply is a boolean indicating whether the request was successful, followed by an optional returned object. By convention, if the request failed, a string indicating the error follows.
["ping"] → [true]
["lock", "/tmp/foo", ["foo", "bar"] ] → [true, [10, 1024, ["foo", "bar"] ] ]
["lock", "/tmp/doesnotexist"] → [false, "mlockfile_lock failed"]
["list"] → [true, {"/tmp/foo":[18, 1024, [] ], "/tmp/bar":[19, 2048, ["baz"] ]}]
- Description
-
Doesn’t do anything.
- Parameters
-
None.
- Returns
-
Nothing (
[true]in case of success,[false, …?]otherwise).
- Description
-
Lists all files currently locked.
- Parameters
-
None.
- Returns
-
Map of files locked in memory, the value takes the form
[fd, size, ["list", "of", "tags"] ].
- Description
-
Locks a file in memory. If this file is already locked, it will be re-locked and its new size will be taken into account. The previous lock is kept until completion. If tags are provided, they are added to the file’s tag list when absent.
- Parameters
-
Path of the file, optional list of tags
- Returns
-
Corresponding file descriptor, size and tags (see
list).
- Description
-
Releases a tag. The tag is removed from all files ; whenever a file loses its last tag it gets unlocked.
- Parameters
-
Tag name.
- Returns
-
Number of untagged files (including unlocked ones), number of untagged files, number of untouched files, number of files that we failed to unlocked.
Our repository contains man pages in man/,
our roadmap in ROADMAP.asciidoc, a list of our most significant contributors in AUTHORS.