v4.0.0

https://github.com/sociomantic-tsunami/ocean/milestone/17

Migration Instructions

All remaining utilities (Stdout, AppStatus, stream...) were switched to Formatter

• ocean.io.Stdout, ocean.io.console.AppStatus, ocean.io.stream.Format,
  ocean.text.Arguments, ocean.util.log.Stats

  All remaining users of ocean.text.convert.Layout[_tango] have been switched to
  the Formatter. For those which see their API affected, the most common use case
  of passing arguments will work just as before. Overriding the formatting
  function will not be possible anymore (as they are template), but redefinition
  is.

  However, forwarding variadic arguments won't work, so functions wishing to
  forward arguments must be defined as templated functions, as shown in
  PeriodicTrace release notes.

  Little difference in output is expected. Pointers will be formatted as
  fixed-length hexadecimal, associative arrays will be formatted as [ Key: value...] instead of { Key: value... }, qualified (const / immutable)
  arguments will be correctly formatted, as well as structs, making the output
  consistent accross ocean (as the Logger module already uses the Formatter).

• ocean.util.log.Stats

  Protected layout field was replaced with protected buffer field which serves
  the same purpose but is a simple AppendBuffer now. Derivative classes have to
  adjust their code to use this.buffer.

Removed legacy template arguments in Logger's configuration module

ocean.util.log.Config : setupLoggerLevel, configureLogger

Those functions used to take a LoggerT template parameter to signify which logger to configure.
As the old logger implementation is now removed, this parameter is now gone.
No disturbance is expected in user's code, as it's unlikely that those parameter were provided explicitly,
since the template parameter was tied to one of the runtime parameter.

Config-based default for console_layout and file_layout

ocean.util.log.Config : Config.{console_layout,file_layout}, configureLoggers

configureLoggers would previously use LayoutDate as the default Layout for the file appender,
and LayoutSimple for the default Layout for the console.
The default would be used whenever the Logger's Config.{console_layout,file_layout} were empty/null.
Instead of relying on this, those field now have a default value of "date" and "simple", respectively,
while will be used by "makeLayout" to instantiate the same default layout.
The only change to users is that setting a null / empty value for those fields is now an error.

The old Tango Layout modules were removed

• ocean.text.convert.Layout, ocean.text.convert.Layout_tango, ocean.core.RuntimeTraits

  Those modules where removed. The Layout one should be completely replaced with the Formatter.
  RuntimeTraits was only used by Layout_tango, and provided incomplete support for its functionalities, especially in D2.

HTTP status reason changed from Ok to OK

ocean.net.http.consts.StatusCodes : StatusPhrase.StatusReasonPhrases

The status reason was changed from "Ok" to "OK". While the previous version
wasn't strictly against the RFC defining HTTP 1.1, it consistently uses "OK"
through the RFC.

Close-on-exec flag is now enabled by default

ocean.sys.CloseOnExec

The default value of the global open_with_close_on_exec flag has been changed from false to true.
In other words, without user actions, file descriptors will have close-on-exec on by default.

Slight change in usage of MultiVersionDecorator.store

ocean.util.serialize.contiguous.MultiVersionDecorator

store method doesn't work with explicit template argument anymore. Simply
removing it and relying on template inference should be sufficient to fix
compilation errors.

Previously it was possible (but not necessary) to explicitly specify serialized
struct type as a template argument. Sadly, it was not possible to keep this
behaviour while introducing additional overloads of store.

Functions which accept an IP address string now report errors via errno

ocean.sys.socket.InetAddress, ocean.sys.socket.AddressIPSocket

Functions which accept an IP address string now report an invalid address by
setting errno = EINVAL. It was EAFNOSUPPORT before, which is wrong because
EAFNOSUPPORT refers to the wrong address family, which is not the case.

This affects the following methods:

• ocean.sys.socket.InetAddress.opCall
• ocean.sys.socket.AddressIPSocket.bind(cstring, ushort)
• ocean.sys.socket.AddressIPSocket.connect(cstring, ushort)

Appender.Layout's format method sink type was updated

ocean.util.log.Appender : Appender.Layout.format

This method was previously accepting a size_t delegate(Const!(void)[]) as sink type.
As we moved away from size_t-returning delegates, and all those layout were essentially
casting the data to cstring under the hood, those delegates were changed to be the same
as FormatterSink (that is, void delegate(cstring)).
Unless you are defining your own Appender.Layout classes, this should not have any effect on you.

Asbtract toHash method now takes in K key instead of K key

ocean.util.container.map.model.BucketSet

Asbtract toHash method was changed to accept in K key instead of just K key. Any class that overrides it directly or indirectly will have to be
adjusted accordingly.

Now getMsg(e) always evaluated to plain e.message()

ocean.transition

Now getMsg(e) always evaluated to plain e.message() call and latter can be
used in application code directly.

PeriodicTrace and StaticTrace were switched to the Formatter

ocean.util.log.PeriodicTrace, ocean.util.log.StaticTrace

Those modules now use ocean.text.convert.Formatter for string formatting
instead of ocean.text.convert.Layout_tango.

As a result, they cannot have runtime variadic arguments forwarded to them (only
PeriodicTrace was offering such an interface). As a result, code forwarding
runtime vararg should switch to CT vararg:

public void trace (cstring fmt, ...)
{
    PeriodicTrace.format(fmt, __va_argsave, _arguments);
}

// Should become:
public void trace (Args...) (cstring fmt, Args args)
{
    PeriodicTrace.format(fmt, args);
}

Non-forwarding usages are expected to be either unaffected or provide better output.

Queue I/O buffer arguments now use void[] instead of ubyte[] and const

ocean.util.container.queue.model.IByteQueue, ocean.util.container.queue.model.IUntypedQueue, ocean.util.container.queue.FixedRingQueue, ocean.util.container.queue.FlexibleFileQueue, ocean.util.container.queue.FlexibleRingQueue, ocean.util.container.queue.NotifyingQueue, ocean.util.container.queue.QueueChain

The types of the arguments and return types for queue input or output buffers
have been changed to void[] and use const where applicable. The particular
methods are:

• bool push ( ubyte[] ) changed to bool push ( in void[] )
• ubyte[] push ( size_t ) changed to void[] push ( size_t )
• bool push ( IUntypedQueue, void[] ) changed to
  bool push ( IUntypedQueue, in void[] )
• bool pop ( ubyte[] ) changed to bool pop ( void[] )
• ubyte[] pop ( ) changed to void[] pop ( )
• ubyte[] peek ( ) changed to void[] peek ( )
• size_t pushSize ( ubyte[] ) changed to size_t pushSize ( in void[] )
• bool willFit ( ubyte[] ) changed to bool willFit ( in void[] )
• void save ( void delegate ( void[] , void[], void[] ) ) changed to
  void save ( void delegate ( in void[], in void[], in void[] ) )

Contiguous (de)serializer does not support recursive types

This struct used to be accepted by serializer but will cause compilation error
with the new ocean:

struct S
{
  S[] x;
}

This is unfortunate side effect of making serializer more generic and separating
type analysis from serialization code. As this feature was not used by
Sociomantic projects and new implementation will simplify maintenance, it was
considered a desirable trade-off.

Old rotation-related fields removed from StatsLog and StatsLog.Config

ocean.util.log.Stats, ocean.util.log.Config

The StatsLog.config and MetaConfig fields max_file_size, file_count, and
start_compress, along with the corresponding default_max_file_size,
default_file_count, and default_start_compress (in StatsLog) have been
removed. These were remnants of the old internal log rotation support in ocean,
which is long gone. Applications should use the logrotate system facility
instead.

Dropped support for non UTF-8 output in stream's FormatOutput / Stdout

ocean.io.Stdout, ocean.io.stream.Format

The TerminalOutput and its parent class FormatOutput dropped support for non UTF-8 character type.
In practice, it means that they were turned from a templated class with one template argument
to a non-templated class.

TimerExt is now swallowing all the unhandled exceptions, keeping the timers registered by default

ocean.util.app.ext.TimerExt

TimerExt is now swallowing all the unhandled exceptions, keeping the timers
registered by default. If you need to unregister the timer on the thrown
exception, catch the exception yourself and manually return false from your
handler.

IConnectionHandler.unregisterSocket made abstract

ocean.net.server.connection.IConnectionHandler

IConnectionHandler.unregisterSocket method, previously implemented with an
empty body is now made abstract, forcing all ConnectionHandlers to unregister
registered socket in a meaningful way before closing them inside the finalizer.
In turn, TaskConnectionHandler now unregisters its transceiver before
closing it.

Example usage:

protected override void unregisterSocket ()
{
    if ( has_registered_client )
        this.registered_client.unregister();
}

The -p option for the unittest runner can't be used as a wildcard any more

core.UnitTestRunner

There is a minor breaking bug fix in the --package / -p option; now it can't be used as some sort of wildcard.

The PKG argument will only match fully qualified names that start with PKG. or the exact module PKG. Before using PKG as argument would have matched PKG*, so PKGfoo was also a match.

As a transitional step, PKG. will also be accepted as a package specification, although it will match both PKG (exact match) and PKG.*.

formatStaticLine method now uses template-based variadic argument

ocean.io.console.AppStatus

formatStaticLine method was changed to use template-based variadic argument
list instead of runtime one.

Changes in --version flag handling and version log + new --build-info

VersionArgsExt used in both CliApp and DaemonApp now implements
--version flag to only print basic version information, without any detailed
build description.

Instead, new --build-info flag is introduced that prints all detailed
information that used to be present in old --version output. However, format
of that output was changed to use plain key=value pairs, one per each line. It
also doesn't treat any keys specially, printing all data found in the supplied
VersionInfo.

Old output:

$ ./app --version
app version v1.0 (compiled by 'author' on today with dmd1 using lib1:v10.0 lib2:v0.5)

New output:

$ ./app --version
app version v1.0
$ ./app --build-info
app version v1.0
build_author=author
build_date=today
compiler=dmd1
lib_lib1=v10.0
lib_lib2=v0.5

Information logged to version.log will match the one printed by --build-info
but will use comma-separated key=value pairs instead of multi-line.

Deprecations

Deprecation of AppendBuffer.deleteContent

ocean.util.container.AppendBuffer

deleteContent method does nothing but force-deleting memory owned by GC and
thus is both unnecessary and potentially dangerous.

Features

Template to recursively check if type contains dynamic arrays

ocean.meta.traits.Indirectons

New containsDynamicArray template is implemented on top of generic
ReduceType facility and provides a more reliable and robust way to detect that
a given type transitively contains some dynamic array.

static struct S
{
  struct Arr { int[] x; }
  Arr[3][4] arr;
}

static assert(containsDynamicArray!(S2));

Several methods now support Buffer!(void) as one of possible buffer types

ocean.util.serialize.contiguous.Serializer
ocean.util.serialize.contiguous.Deserializer
: serialize and in-place deserialize

ocean.util.serialize.contiguous.MultiVersionDecorator : store and in-place load

Old void[] and derivatives are still supported too.

Copy TemplateInstanceArgs to ocean.meta

Old ocean.core.Traits.TemplateInstanceArgs template is now also available
as ocean.meta.types.Templates.TemplateInstanceArgs (no implementation
changes).

Interactive session over the unix domain socket.

ocean.net.server.unix.UnixListener, ocean.net.server.unix.UnixConnectionHandler, ocean.util.app.ext.UnixSocketExt

UnixConnectionHandler now accepts the map of the interactive handlers -
delegates that accept additional delegate argument: wait_reply. These handlers
can initiate interactive session with the user by sending the data via
send_response and waiting for the user to reply via wait_reply.