Struct Server 

pub struct Server {
    pub stats: Stats,
    /* private fields */
}

Everything a server holds.

One of these per shard thread, not one per process: the databases inside are not Sync and are reached by sending their thread a command. What makes this a server rather than a shard is that it is the whole of what a connection can address.

Fields

stats: Stats

The numbers the reactor keeps for INFO.

Implementations

impl Server

pub fn now_ms(&self) -> u64

The clock reading this batch is working against.

pub const fn waiters(&self) -> &Waiters

Who is parked, for the engine and for INFO.

pub const fn waiters_mut(&mut self) -> &mut Waiters

The same, for the engine, which is what binds and forgets them.

pub fn serve_waiter(&mut self, at: usize, now: u64, out: &mut Out) -> bool

Try to answer the waiter at at, writing into the buffer the engine found for it, and say whether it is finished with.

The engine cannot reach the databases and this cannot reach the connections, so the two meet here: the caller hands in one connection’s reply buffer and gets back whether to unpark the client behind it.

Panics

If at is not a waiter.

impl Server

pub fn new() -> Server

A server with DATABASES empty databases on the system clock.

pub fn with_clock(clock: Clock) -> Server

A server on a clock the caller moves by hand, for tests.

pub fn db(&mut self, i: usize) -> &mut Keyspace

One database, by index.

Panics

If i is not a database. SELECT is the only way a client changes the index and it checks, so an index that is out of range here is a bug in the caller and not something a client can ask for.

pub fn dir(&self) -> &Path

Where BACKUP writes and what CONFIG GET dir answers.

pub fn set_dir(&mut self, dir: PathBuf)

Point the server at a different directory, which yodb serve --dir does.

Only before it is serving. There is no CONFIG SET dir here and there is none on a real server either without turning protected configs on, for the good reason that moving it out from under a running backup would leave files nothing can find again.

pub fn backup_expire(&mut self)

Drop a sealed backup that has outlived backup-sealed-ttl.

Once per batch, from the same maintenance turn that collects the arena. It reads two fields and returns on a server that has never taken a backup, which is nearly all of them.

pub fn stop(&mut self)

Ask for the server to stop, which is what SHUTDOWN does.

It sets a flag and returns. Nothing here closes a socket, flushes a file or ends the process, because none of those belong to this layer, and a batch that is halfway through still has to finish and be written out.

pub fn stopping(&self) -> bool

Whether somebody has asked the server to stop.

Read once per turn by the loop, next to the flag a signal sets. The two mean the same thing and are separate only because one arrives from the operating system and the other from a client.

pub fn db_ref(&self, i: usize) -> &Keyspace

One database, by index, without taking it mutably.

What the prefetch stage needs. It runs for all 64 commands in a batch before any of them executes, so it cannot hold the mutable borrow run is about to want, and it does not need one: warming a cache line reads nothing and changes nothing.

Panics

As Server::db.

pub fn refresh_clock(&mut self)

Take a new clock reading and give it to every database.

Once per turn of the event loop, which is the only place time moves. A command asking what the time is gets the answer the whole batch got, so two keys written by the same batch expire together (04 section 3).

pub fn set_clock_ms(&mut self, ms: u64)

Move every clock here to ms by hand, for tests about expiry.

A test cannot wait a hundred seconds and a test that waits a hundred milliseconds is a test that fails on a loaded machine, so time moves on request. The system clock underneath will overwrite this on the next Server::refresh_clock, which is why this is only useful in a test that drives commands directly rather than through the event loop.

pub fn uptime_secs(&self) -> u64

Seconds since this server was built.

pub fn memory_bytes(&self) -> usize

Bytes held by every database’s index and arena, plus the read and reply buffers of every connection.

The buffers are in here because they are real and because Redis counts its own, so leaving them out would make the one number people compare flattering rather than true. They are not a database, so nothing in the keyspace can change them and the engine has to say when they move.

pub fn dataset_bytes(&self) -> usize

What the keyspace itself is holding, live records only.

used_memory minus this is what the store costs to run: the index, the space dead records are sitting in until compaction gets to them, and the connections’ buffers.

pub fn arena_bytes(&self) -> usize

Bytes the arenas are holding, live and dead together.

pub fn index_bytes(&self) -> usize

Bytes the indexes are holding.

pub fn compaction(&self) -> Compaction

What arena compaction has cost, across every database.

The write amplification of value separation, which is invisible from the outside otherwise: a client that writes a megabyte can leave the store copying several more, and the only sign of it without these is that the writes got slower.

pub fn segment_count(&self) -> usize

Arena segments whose pages are real, across every database.

pub const fn conn_bytes(&self) -> usize

What the connections’ read and reply buffers are holding.

pub fn note_conn_bytes(&mut self, delta: isize)

Note that the connections are holding delta bytes more than they were, or fewer when it is negative.

A delta and not a total because the alternative is a walk over every connection, and the walk would have to happen on a turn of the loop rather than when INFO asks, which puts the cost of a report on the command path of a server nobody is asking.

pub fn expired_keys(&self) -> u64

Keys reclaimed by running into them after their deadline.

pub fn evicted_keys(&self) -> u64

Keys thrown away to make room, which is the other number entirely.

pub fn command_stats(&self) -> impl Iterator<Item = (&'static str, CommandStat)>

Every command that has been seen, with its counters.

Only the ones that have. A server reports a handful of lines rather than one per command in the table, which is what Redis does and is the difference between a section a person can read and one they cannot.

pub const fn maxmemory(&self) -> u64

The maxmemory limit in bytes, zero when there is not one.

pub fn set_maxmemory(&mut self, bytes: u64)

Set the limit, and take a reading straight away.

The reading is here rather than left to the next maintenance turn because a client that sets the limit and sends a write in the same batch expects the write to be judged against the limit it just set, and because the cached number is meaningless until the first time there is a limit to compare it with.

Turning the limit on also turns on the running total every slab keeps of what its collections hold, and turning it off turns that back off, so a server with no limit is not paying to count something nobody reads. The first reading after switching it on is the walk that the total starts from, and it is the only walk.

pub fn set_store_source( &mut self, source: impl FnMut(usize) -> Option<Box<dyn Blocks>> + 'static, )

Say where a database should get its store from when it needs one.

This is what turns the eviction inversion on. Until it is called every database answers a memory limit by evicting, which is Redis, and after it is called a database under memory pressure moves values to whatever the closure hands back instead of throwing keys away.

Called at most once per database and only under pressure, so a server that is given a file and never fills memory never touches it.

pub const fn has_store_source(&self) -> bool

Whether this server has been given somewhere to put cold values.

pub const fn maxstore(&self) -> Option<u64>

The maxstore limit in bytes, None when there is not one.

pub const fn set_maxstore(&mut self, bytes: Option<u64>)

Set the storage limit, or clear it with None.

Nothing is read here the way Server::set_maxmemory reads the memory total, because this limit is compared against a number the store keeps and answers on demand, not against a walk.

pub fn store_bytes(&self) -> u64

What every attached store is holding, for INFO memory.

Zero on a server with nothing attached, which is not the same as a server whose file is empty, and Server::regime is the field that tells those two apart.

pub fn cold_stats(&self) -> Stats

What the file has been asked to do, added up over every database.

Counters and not levels, so they only ever go up and a run is the difference between two readings. G9 is a ratio over these: the faults a run took, divided by the point reads it issued, has to come out at 1.05 or less with a working set ten times memory. There is no way to work that out from outside the server, so it is reported rather than inferred.

A fault is a read that went to the store. Whether it also went to the device depends on the store: a log serves a read out of a resident page without touching anything. At ten times memory almost every fault is a real read, which is why the gate is written against this number, but the two are not the same thing and a run tight against the bar should be checked against what the operating system says.

pub fn regime(&self) -> &'static str

Which way this server answers a memory limit, in one word for INFO.

evict is Redis: a memory limit throws keys away. migrate is the inversion: a memory limit moves values to the file and nothing stored is lost. A server reports one word rather than leaving an operator to work it out from a limit, a setting and whether a file happens to be open.

pub fn refresh_memory(&mut self)

Take a fresh memory reading, which the maintenance turn does once a batch.

Nothing at all when there is no limit, which is the default and is every server that has not asked for one.

pub fn make_room(&mut self) -> bool

Make room under the maxmemory limit, throwing keys away if that is what it takes. Answers whether there is anything left it could throw away.

Redis runs the same thing from processCommand before every command and so does this: a client that writes has to be judged at the moment it writes, not a batch later, or the limit is a suggestion.

Three things happen in the loop and all three are needed. Eviction picks a key and drops it. Compaction gives the pages back, because dropping a key marks its record dead and returns nothing on its own, so a loop that only evicted would throw the whole keyspace away and watch the number stay where it was. The reading is taken again each time round, because the two of them together are the only thing that moves it.

Why running out of budget is not a no

false means there was nothing left to evict, which is noeviction, or a volatile policy on a database where nothing has a deadline, or a keyspace that is already empty. It does not mean the server is still over its limit, and that difference is Redis’s: performEvictions answers EVICT_FAIL only when it has run out of things to delete, and processCommand refuses the client on that and on nothing else. Running out of time part way through a job it is doing well comes back as EVICT_RUNNING and the command goes through, because a server that is evicting steadily and refusing every write while it does it is worse for the client than a little overshoot.

What the limit is worth

Space comes back a segment at a time and a segment is two megabytes, so this holds a server to its limit give or take a segment. A maxmemory of a few hundred megabytes gets what it asked for. A maxmemory of four megabytes is asking for a precision this store does not have.

pub fn expire_slice(&mut self, budget: usize) -> usize

The sweep the shard loop calls, at most once a millisecond.

The gate is the whole difference between this and Server::expire_step. A maintenance slice runs on every turn of the loop and a turn is a hundred nanoseconds, so an ungated sweep would draw a fresh sample ten thousand times per millisecond and spend a real share of the shard on looking for keys that cannot have died since the last look. Nothing in a database changes fast enough to be worth asking about more often than the clock can tell the difference, and the clock here is milliseconds.

A millisecond is also far finer than Redis, whose slow cycle runs at ten hertz, so this is not the thing that decides how promptly memory comes back. What it decides is that an idle server sweeps a thousand times a second rather than a million.

pub fn expire_step(&mut self, budget: usize) -> usize

Sweep dead keys out of the databases, spending at most budget looks.

Answers what it spent, so the caller can charge its maintenance slice for it. See yo_kv::expiry for why the budget is in keys looked at.

Round robin from its own cursor, and every database gets offered whatever is left of the budget rather than a sixteenth of it each, so a server on database zero only, which is nearly every server, spends the whole slice where the keys are. The fifteen empty ones cost a comparison apiece because a database with no key carrying a deadline says so without drawing anything.

The cursor moves to the database after whichever one did the work, so two busy databases take turns instead of the lower numbered one starving the other.

pub fn compact_step(&mut self) -> Option<usize>

Give one database’s dead space back, if any database has enough of it to be worth the move. None when no database had a candidate.

Once per batch, next to the clock. Overwriting a key writes a new record and counts the old one dead, so without this a server holds everything it has ever written: 400000 sets over 100000 keys measured at 742 bytes a key against Redis at 144 for the same load, and the whole difference was dead records nothing ever came back for.

At most one segment moves per call and the search starts one database further along each time, so the cost of asking is a comparison per database and the cost of acting is bounded by a segment.

Trait Implementations

impl Default for Server

fn default() -> Server

Returns the “default value” for a type.