arsd.core

ditto

A wrapper around a const(char)* to indicate that it is a zero-terminated C string.

A packed date/time/datetime representation added for use with LimitedVariant.

You should probably not use this much directly, it is mostly an internal storage representation.

A PackedInterval can be thought of as the difference between [PackedDateTime]s, similarly to how a [Duration] is a difference between [MonoTime]s or [SimplifiedUtcTimestamp]s.

The key speciality is in how it treats months and days separately. Months are not a consistent length, and neither are days when you consider daylight saving time. This thing assumes that if you add those, the month/day number will always increase, just the exact details since then might be truncated. (E.g., January 31st + 1 month = February 28/29 depending on leap year). If you multiply, the parts are done individually, so January 31st + 1 month * 2 = March 31st, despite + 1 month truncating to the shorter day in February.

Internally, this stores months and days as 16 bit signed shorts each, then the milliseconds is stored as a 32 bit signed int. It applies by first adding months, truncating days as needed, then adding days, then adding milliseconds.

If you iterate over intervals, be careful not to allow month truncation to change the result. (Jan 31st + 1 month) + 1 month will not actually give the same result as Jan 31st + 2 months. You want to add to the interval, then apply to the original date again, not to some accumulated date.

Basically a Phobos SysTime but standing alone as a simple 64 bit integer (but wrapped) for compatibility with LimitedVariant.

A little builder pattern helper that is meant for use by other library code.

Represents a generic raw element to be embedded in an interpolated sequence.

Use with caution, its exact meaning is dependent on the specific function being called, but it generally is meant to disable encoding protections the function normally provides.

A limited variant to hold just a few types. It is made for the use of packing a small amount of extra data into error messages and some transit across virtual function boundaries.

Note that empty strings and null values are indistinguishable unless you explicitly slice the end of some other existing string!

A DynamicDecimal is a fixed-point object whose precision is dynamically typed.

It packs everything into a 64 bit value. It uses one bit for sign, three bits for precision, then the rest of them for the value. This means the precision (that is, the number of digits after the decimal) can be from 0 to 7, and there can be a total of 18 digits.

Numbers can be added and subtracted only if they have matching precision. They can be multiplied and divided only by whole numbers.

This is a dummy type to indicate the end of normal arguments and the beginning of the file/line inferred args. It is meant to ensure you don't accidentally send a string that is interpreted as a filename when it was meant to be a normal argument to the function and trigger the wrong overload.

Basically a scope class you can return from a function or embed in another aggregate.

Alternative for toStringz

ditto

ditto

Declares a delegate property with several setters to allow for handlers that don't care about the arguments.

Throughout the arsd library, you will often see types of these to indicate that you can set listeners with or without arguments. If you care about the details of the callback event, you can set a delegate that declares them. And if you don't, you can set one that doesn't even declare them and it will be ignored.

Base class representing my exceptions. You should almost never work with this directly, but you might catch it as a generic thing. Catch it before generic object.Exception or object.Throwable in any catch chains.

General guidelines for exceptions

The purpose of an exception is to cancel a task that has proven to be impossible and give the programmer enough information to use at a higher level to decide what to do about it.

Cancelling a task is accomplished with the throw keyword. The transmission of information to a higher level is done by the language runtime. The decision point is marked by the catch keyword. The part missing - the job of the Exception class you construct and throw - is to gather the information that will be useful at a later decision point.

It is thus important that you gather as much useful information as possible and keep it in a way that the code catching the exception can still interpret it when constructing an exception. Other concerns are secondary to this to this primary goal.

With this in mind, here's some guidelines for exception handling in arsd code.

Allocations and lifetimes

Don't get clever with exception allocations. You don't know what the catcher is going to do with an exception and you don't want the error handling scheme to introduce its own tricky bugs. Remember, an exception object's first job is to deliver useful information up the call chain in a way this code can use it. You don't know what this code is or what it is going to do.

Keep your memory management schemes simple and let the garbage collector do its job.

• All thrown exceptions should be allocated with the new keyword.
• Members inside the exception should be value types or have infinite lifetime (that is, be GC managed).
• While this document is concerned with throwing, you might want to add additional information to an in-flight exception, and this is done by catching, so you need to know how that works too, and there is a global compiler switch that can change things, so even inside arsd we can't completely avoid its implications.

DIP1008's presence complicates things a bit on the catch side - if you catch an exception and return it from a function, remember to ex.refcount = ex.refcount + 1; so you don't introduce more use-after-free woes for those unfortunate souls.

Error strings

Strings can deliver useful information to people reading the message, but are often suboptimal for delivering useful information to other chunks of code. Remember, an exception's first job is to be caught by another block of code. Printing to users is a last resort; even if you want a user-readable error message, an exception is not the ideal way to deliver one since it is constructed in the guts of a failed task, without the higher level context of what the user was actually trying to do. User error messages ought to be made from information in the exception, combined with higher level knowledge. This is best done in a catch block, not a throw statement.

As such, I recommend that you:

• Don't concatenate error strings at the throw site. Instead, pass the data you would have used to build the string as actual data to the constructor. This lets catchers see the original data without having to try to extract it from a string. For unique data, you will likely need a unique exception type. More on this in the next section.
• Don't construct error strings in a constructor either, for the same reason. Pass the useful data up the call chain, as exception members, to the maximum extent possible. Exception: if you are passed some data with a temporary lifetime that is important enough to pass up the chain. You may .idup or to!string to preserve as much data as you can before it is lost, but still store it in a separate member of the Exception subclass object.
• Do construct strings out of public members in [getAdditionalPrintableInformation]. When this is called, the user has requested as much relevant information as reasonable in string format. Still, avoid concatenation - it lets you pass as many key/value pairs as you like to the caller. They can concatenate as needed. However, note the words "public members" - everything you do in getAdditionalPrintableInformation ought to also be possible for code that caught your exception via your public methods and properties.

Subclasses

Any exception with unique data types should be a unique class. Whenever practical, this should be one you write and document at the top-level of a module. But I know we get lazy - me too - and this is why in standard D we'd often fall back to throw new Exception("some string " ~ some info). To help resist these urges, I offer some helper functions to use instead that better achieve the key goal of exceptions - passing structured data up a call chain - while still being convenient to write.

See: [ArsdException], [Win32Enforce]

Base class for when you've requested a feature that is not available. It may not be available because it is possible, but not yet implemented, or it might be because it is impossible on your operating system.

This means the feature could be done, but I haven't gotten around to implementing it yet. If you email me, I might be able to add it somewhat quickly and get back to you.

This means the feature is not supported by your current operating system. You might be able to get it in an update, but you might just have to find an alternate way of doing things.

A tagged union that holds an error code from system apis, meaning one from Windows GetLastError() or C's errno.

You construct it with SystemErrorCode(thing) and the overloaded constructor tags and stores it.

You can also pass a handle to a specific thread, if you have one.

The internal types that will be exposed through other api things.

This represents a file. Technically, file paths aren't actually strings (for example, on Linux, they need not be valid utf-8, while a D string is supposed to be), even though we almost always use them like that.

This type is meant to represent a filename / path. I might not keep it around.

ditto

Specialization of string to indicate it is a URI. You should generally use arsd.uri.Uri instead of this in user code.

Shared base code for web socket client in arsd.http2 and server in arsd.cgi.

Represents a generic async, waitable request.

ditto

Some functions that return arrays allow you to provide your own buffer. These are indicated in the type system as UserProvidedBuffer!Type, and you get to decide what you want to happen if the buffer is too small via the [OnOutOfSpace] parameter.

These are usually optional, since an empty user provided buffer with the default policy of reallocate will also work fine for whatever needs to be returned, thanks to the garbage collector taking care of it for you.

The API inside UserProvidedBuffer is all private to the arsd library implementation; your job is just to provide the buffer to it with provideBuffer or a constructor call and decide on your on-out-of-space policy.

properly size a buffer, I suggest looking at what covers about 80% of cases. Trying to cover everything often leads to wasted buffer space, and if you use a reallocate policy it can cover the rest. You might be surprised how far just two elements can go!

Possible policies for [UserProvidedBuffer]s that run out of space.

ditto

PARTIALLY IMPLEMENTED / NOT STABLE

This starts up a local pipe. If it is already claimed, it just communicates with the existing one through the interface.

This is primarily a helper for the event queues. It is public in the hope it might be useful, but subject to change without notice; I will treat breaking it the same as if it is private. (That said, it is a simple little utility that does its job, so it is unlikely to change much. The biggest change would probably be letting it grow and changing from inline to dynamic array.)

It is a fixed-size ring buffer that synchronizes on a given object you give it in the constructor.

After enqueuing something, you should probably set an event to notify the other threads. This is left as an exercise to you (or another wrapper).

A class to help write a stream of binary data to some target.

NOT YET FUNCTIONAL

UNSTABLE, NOT FULLY IMPLEMENTED. DO NOT USE YET.

You might use this like:

auto proc = new ExternalProcess();
auto stdoutStream = new ReadableStream();

// to use a stream you can make one and have a task consume it
runTask({
	while(!stdoutStream.isClosed) {
		auto line = stdoutStream.get!string(e => e == '\n');
	}
});

// then make the process feed into the stream
proc.onStdoutAvailable = (got) {
	stdoutStream.feedData(got); // send it to the stream for processing
	stdout.rawWrite(got); // forward it through to our own thing
	// could also append it to a buffer to return it on complete
};
proc.start();

Please note that this does not currently and I have no plans as of this writing to add support for any kind of direct file descriptor passing. It always pipes them back to the parent for processing. If you don't want this, call the lower level functions yourself; the reason this class is here is to aid integration in the arsd.core event loop. Of course, I might change my mind on this.

DO NOT USE THIS YET IT IS NOT FUNCTIONAL NOR STABLE

The arsd.core logger works differently than many in that it works as a ring buffer of objects that are consumed (or missed; buffer overruns are possible) by a different thread instead of strings written to some file.

A library (or an application) defines a log source. They write to this source.

Applications then define log listeners, zero or more, which reads from various sources and does something with them.

Log calls, in this sense, are quite similar to asynchronous events that can be subscribed to by event handlers. The difference is events are generally not dropped - they might coalesce but are usually not just plain dropped in a buffer overrun - whereas logs can be. If the log consumer can't keep up, the details are just lost. The log producer will not wait for the consumer to catch up.

An application can also set a default subscriber which applies to all log objects throughout.

All log message objects must be capable of being converted to strings and to json.

Ad-hoc messages can be done with interpolated sequences.

Messages automatically get a timestamp. They can also have file/line and maybe even a call stack.

auto logger = new shared LoggerOf!GenericEmbeddableInterpolatedSequence;

mylogger.info(i"$this heartbeat");

ditto

ditto

ditto

ditto

Represents a translatable string.

This depends on interpolated expression sequences to be ergonomic to use and in most cases, a function that uses this should take it as tstring name...; a typesafe variadic (this is also why it is a class rather than a struct - D only supports this particular feature on classes).

You can use null as a tstring. You can also construct it with UFCS: i"foo".tstring.

The actual translation engine should be set on the application level.

It is possible to get all translatable string templates compiled into the application at runtime.

ditto

You can use mixin(dumpParams); to put out a debug print of your current function call w/ params.

This populates a struct from a list of values (or other expressions, but it only looks at the values) based on types of the members, with one exception: bool members.. maybe.

It is intended for collecting a record of relevant UDAs off a symbol in a single call like this:

struct Name {
	string n;
}

struct Validator {
	string regex;
}

struct FormInfo {
	Name name;
	Validator validator;
}

@Name("foo") @Validator(".*")
void foo() {}

auto info = populateFromUdas!(FormInfo, __traits(getAttributes, foo));
assert(info.name == Name("foo"));
assert(info.validator == Validator(".*"));

Note that instead of UDAs, you can also pass a variadic argument list and get the same result, but the function is populateFromArgs and you pass them as the runtime list to bypass "args cannot be evaluated at compile time" errors:

void foo(T...)(T t) {
	auto info = populateFromArgs!(FormInfo)(t);
	// assuming the call below
	assert(info.name == Name("foo"));
	assert(info.validator == Validator(".*"));
}

foo(Name("foo"), Validator(".*"));

The benefit of this over constructing the struct directly is that the arguments can be reordered or missing. Its value is diminished with named arguments in the language.

Given a function and a parameter index, returns a function that only takes that parameter and returns it. If called with zero arguments, it returns the default value, if it exists. If not, you'll get a compiler error.

Note that it is a function because function parameters in D can have function calls, including side effects, as a default argument.

firstDefaultParam returns the index of the first defaultParam for the given function fn that can be called without an argument.

On older compilers, firstDefaultParam may always be parameters.length, since defaultParam requires a relatively new language feature (__traits(parameters), introduced in upstream D 2.099.0, released March 6, 2022).

This is a generic exception with attached arguments. It is used when I had to throw something but didn't want to write a new class.

You can catch an ArsdException to get its passed arguments out.

You can pass either a base class or a string as Type.

See the examples for how to use it.

Calls the C API function fn. If it returns an error value, it throws an [ErrnoApiException] (or subclass) after getting errno.