arsd.core

Shared core functionality including exception helpers, library loader, event loop, and possibly more. Maybe command line processor and uda helper and some basic shared annotation types.

I'll probably move the url, websocket, and ssl stuff in here too as they are often shared.

If you use this directly outside the arsd library, you might consider using static import since names in here are likely to clash with Phobos if you use them together. static import will let you easily disambiguate and avoid name conflict errors if I add more here. Some names even clash deliberately to remind me to avoid some antipatterns inside the arsd modules!

Members

Aliases

ErrnoApiException
alias ErrnoApiException = SystemApiException
WindowsApiException
alias WindowsApiException = SystemApiException

The low level use of this would look like throw new WindowsApiException("MsgWaitForMultipleObjectsEx", GetLastError()) but it is meant to be used from higher level things like Win32Enforce.

Classes

ArsdExceptionBase
class ArsdExceptionBase

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.

AsyncOperationRequest
class AsyncOperationRequest

Represents a generic async, waitable request.

AsyncOperationResponse
class AsyncOperationResponse
AsyncReadRequest
class AsyncReadRequest
Undocumented in source.
AsyncWriteRequest
class AsyncWriteRequest

You can write to a file asynchronously by creating one of these.

ExternalProcess
class ExternalProcess

You might use this like:

ReadableStream
class ReadableStream

A stream can be used by just one task at a time, but one task can consume multiple streams.

SyncFile
class SyncFile
SystemApiException
class SystemApiException

Enums

ByteOrder
enum ByteOrder
EventLoopType
enum EventLoopType

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

ThreadToRunIn
enum ThreadToRunIn

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

WindowsStringConversionFlags
enum WindowsStringConversionFlags

Used by makeWindowsString and WCharzBuffer

Functions

arsd_core_init
void arsd_core_init(int numberOfWorkers)

Initializes the arsd core event loop and creates its worker threads. You don't actually have to call this, since the first use of an arsd.core function that requires it will call it implicitly, but calling it yourself gives you a chance to control the configuration more explicitly if you want to.

asTheyComplete
AsTheyCompleteRange asTheyComplete(AsyncOperationRequest[] requests)

Waits for all the requests to complete, giving each one through the range interface as it completes.

getThisThreadEventLoop
ICoreEventLoop getThisThreadEventLoop(EventLoopType type)

Get the event loop associated with this thread

intToString
char[] intToString(long value, char[] buffer, IntToStringArgs args)

An int printing function that doesn't need to import Phobos. Can do some of the things std.conv.to and std.format.format do.

makeUtf8StringFromWindowsString
char[] makeUtf8StringFromWindowsString(wchar[] str, char[] buffer)

Converts the Windows API string str to a D UTF-8 string, storing it in buffer. Returns the slice of buffer actually used.

makeUtf8StringFromWindowsString
string makeUtf8StringFromWindowsString(wchar[] str)
string makeUtf8StringFromWindowsString(wchar* str)

Converts the Windows API string str to a newly-allocated D UTF-8 string.

makeWindowsString
wchar[] makeWindowsString(char[] str, wchar[] buffer, int conversionFlags)

Given the string str, converts it to a string compatible with the Windows API and puts the result in buffer, returning the slice of buffer actually used. buffer must be at least sizeOfConvertedWstring elements long.

mallocSlice
T[] mallocSlice(size_t n)

A trivial wrapper around C's malloc that creates a D slice. It multiples n by T.sizeof and returns the slice of the pointer from 0 to n.

mallocedStringz
char[] mallocedStringz(char[] original)

Uses C's malloc to allocate a copy of original with an attached zero terminator. It may return a slice with a null pointer (but non-zero length!) if malloc fails and you are responsible for freeing the returned pointer with core.stdc.stdlib.free(ret.ptr).

populateFromArgs
Struct populateFromArgs(Args args)

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.

sizeOfConvertedWstring
int sizeOfConvertedWstring(char[] s, int conversionFlags)

Returns a minimum buffer length to hold the string s with the given conversions. It might be slightly larger than necessary, but is guaranteed to be big enough to hold it.

stripInternal
inout(char)[] stripInternal(inout(char)[] s)
toStringInternal
string toStringInternal(T t)

Shortcut for converting some types to string without invoking Phobos (but it will as a last resort).

waitForFirstToComplete
AsyncOperationRequest waitForFirstToComplete(AsyncOperationRequest[] requests)
waitForFirstToCompleteByIndex
size_t waitForFirstToCompleteByIndex(AsyncOperationRequest[] requests)

It returns the request so you can identify it more easily. request.waitForCompletion() is guaranteed to return the response without any actual wait, since it is already complete when this function returns.

Interfaces

ICoreEventLoop
interface ICoreEventLoop

Structs

ArgSentinel
struct ArgSentinel

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.

AsTheyCompleteRange
struct AsTheyCompleteRange

Waits for all the requests to complete, giving each one through the range interface as it completes.

CharzBuffer
struct CharzBuffer

Alternative for toStringz

FilePath
struct FilePath

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.

FlexibleDelegate
struct FlexibleDelegate(DelegateType)

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

IntToStringArgs
struct IntToStringArgs

An int printing function that doesn't need to import Phobos. Can do some of the things std.conv.to and std.format.format do.

OwnedClass
struct OwnedClass(Class)

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

PresenceOf
struct PresenceOf(alias a)

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.

SynchronizedCircularBuffer
struct SynchronizedCircularBuffer(T, size_t maxSize = 128)

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

SystemErrorCode
struct SystemErrorCode

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

WCharzBuffer
struct WCharzBuffer

A helper object for temporarily constructing a string appropriate for the Windows API from a D UTF-8 string.

stringz
struct stringz

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

Templates

ArsdException
template ArsdException(alias Type, DataTuple...)

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

ErrnoEnforce
template ErrnoEnforce(alias fn, alias errorValue = void)

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

Win32Enforce
template Win32Enforce(alias fn, alias errorValue = void)

Calls the Windows API function fn. If it returns an error value, it throws a WindowsApiException (or subclass) after calling GetLastError().

populateFromUdas
template populateFromUdas(Struct, UDAs...)

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.

Meta

History

Added March 2023 (dub v11.0). Several functions were migrated in here at that time, noted individually. Members without a note were added with the module.