Skip to content

Latest commit

 

History

History
106 lines (86 loc) · 3.37 KB

pcma.5.asciidoc

File metadata and controls

106 lines (86 loc) · 3.37 KB
Raw

PCMA(5) Manual Page

NAME

pcma - Page Cache My Assets

SYNOPSIS

pcma(5) provides a network protocol, server and reference client to warm up the page cache and avoid page cache eviction.

IMPLEMENTATION

  • 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) and mlock(2).

  • Locking only affects the beginning of the file, up to the size observed when locking. Files can be re-locked if needed.

WARNING

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.

PROTOCOL

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.

EXAMPLES

["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"] ]}]

COMMANDS

ping

Description

Doesn’t do anything.

Parameters

None.

Returns

Nothing ([true] in case of success, [false, …​?] otherwise).

list

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"] ].

lock

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).

unlock

Description

Unlocks a file.

Parameters

Path of the file.

Returns

Nothing (see ping).

releasetag

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.

SEE ALSO

Our repository contains man pages in man/, our roadmap in ROADMAP.asciidoc, a list of our most significant contributors in AUTHORS.