• About this document
• Void type
• Genericdefine pragma
• Top-down type inference
• Inferred generic parameters
• Sequence literals
• Package level objects
• Importing private symbols
• Code reordering
• Special Operators
• dot operators
• operator.
• operator.()
• operator.=
• Call operator
• Extended macro pragmas
• Symbols as template/macro calls (alias syntax)
• Not nil annotation
• Strict not nil checking
• nil
• not nil
• local turn on/off
• nilability state
• type nilability
• params rules
• assignment rules
• call args rules
• branches rules
• compound expressions: field, index expressions
• element tracking
• unstructured control flow rules
• aliasing
• warnings and errors
• Aliasing restrictions in parameter passing
• Strict funcs
• View types
• Path expressions
• Start of a borrow
• End of a borrow
• Reborrows
• Algorithm
• Concepts
• Concept diagnostics
• Generic concepts and type binding rules
• Concept derived values
• Concept refinement
• Dynamic arguments for bindSym
• Term rewriting macros
• Parameter constraints
• Pattern operators
• The| operator
• The{} operator
• The~ operator
• The* operator
• The** operator
• Parameters
• noRewrite pragma
• Example: Partial evaluation
• Example: Hoisting
• AST based overloading
• Parallel & Spawn
• Spawn statement
• Parallel statement
• Strict definitions andout parameters
• out parameters
• Out parameters and exception handling
• Out parameters and inheritance
• Strict case objects
• Quirky routines
• Threading under ARC/ORC
• Isolation
• Alias analysis
• Sendable pragma
• Virtual pragma
• Constructor pragma
• Constructor Initializer
• Member pragma
• Injected symbols in generic procs and templates
• VTable for methods
• asmSyntax pragma
• Type-bound overloads

About this document

This document describes features of Nim that are to be considered experimental. Some of these are not covered by the.experimental pragma or--experimental switch because they are already behind a special syntax and one may want to use Nim libraries using these features without using them oneself.

Void type

Thevoid type denotes the absence of any value, i.e. it is the type that contains no values. Consequently, no value can be provided for parameters of typevoid, and no value can be returned from a function with return typevoid:

procnothing(x,y:void):void=echo"ha"nothing()# writes "ha" to stdout

Thevoid type is particularly useful for generic code:

proccallProc[T](p:proc(x:T),x:T)=whenTisvoid:p()else:p(x)procintProc(x:int)=discardprocemptyProc()=discardcallProc[int](intProc,12)callProc[void](emptyProc)

However, avoid type cannot be inferred in generic code:

callProc(emptyProc)# Error: type mismatch: got (proc ())# but expected one of:# callProc(p: proc (T), x: T)

Thevoid type is only valid for parameters and return types; other symbols cannot have the typevoid.

Genericdefine pragma

Aside thetyped define pragmas for constants, there is a generic{.define.} pragma that interprets the value of the define based on the type of the constant value.

constfoo{.define:"package.foo".}=123constbar{.define:"package.bar".}=false

nimc-d:package.foo=456-d:package.barfoobar.nim

The following types are supported:

• string andcstring
• Signed and unsigned integer types
• bool
• Enums

Top-down type inference

In expressions such as:

leta:T=ex

Normally, the compiler type checks the expressionex by itself, then attempts to statically convert the type-checked expression to the given typeT as much as it can, while making sure it matches the type. The extent of this process is limited however due to the expression usually having an assumed type that might clash with the given type.

With top-down type inference, the expression is type checked with the extra knowledge that it is supposed to be of typeT. For example, the following code is does not compile with the former method, but compiles with top-down type inference:

letfoo:(float,uint8,cstring)=(1,2,"abc")

The tuple expression has an expected type of(float,uint8,cstring). Since it is a tuple literal, we can use this information to assume the types of its elements. The expected types for the expressions1,2 and"abc" are respectivelyfloat,uint8, andcstring; and these expressions can be statically converted to these types.

Without this information, the type of the tuple expression would have been assumed to be(int,int,string). Thus the type of the tuple expression would not match the type of the variable, and an error would be given.

The extent of this varies, but there are some notable special cases.

Inferred generic parameters

In expressions making use of generic procs or templates, the expected (unbound) types are often able to be inferred based on context. This feature has to be enabled via{.experimental:"inferGenericTypes".}

{.experimental:"inferGenericTypes".}importstd/optionsvarx=newSeq[int](1)# Do some work on 'x'...# Works!# 'x' is 'seq[int]' so 'newSeq[int]' is impliedx=newSeq(10)# Works!# 'T' of 'none' is bound to the 'T' of 'noneProducer', passing it along.# Effectively 'none.T = noneProducer.T'procnoneProducer[T]():Option[T]=none()letmyNone=noneProducer[int]()# Also works# 'myOtherNone' binds its 'T' to 'float' and 'noneProducer' inherits it# noneProducer.T = myOtherNone.TletmyOtherNone:Option[float]=noneProducer()# Works as well# none.T = myOtherOtherNone.TletmyOtherOtherNone:Option[int]=none()

This is achieved by reducing the types on the lhs and rhs until thelhs is left with only types such asT. While lhs and rhs are reduced together, this doesnot mean that therhs will also only be left with a flat typeZ, it may be of the formMyType[Z].

After the types have been reduced, the typesT are bound to the types that are left on the rhs.

If bindingscannot be inferred, compilation will fail and manual specification is required.

An example forfailing inference can be found when passing a generic expression to a function/template call:

{.experimental:"inferGenericTypes".}procmyProc[T](a,b:T)=discard# Fails! Unable to infer that 'T' is supposed to be 'int'myProc(newSeq[int](),newSeq(1))# Works! Manual specification of 'T' as 'int' necessarymyProc(newSeq[int](),newSeq[int](1))

Combination of generic inference with theauto type is also unsupported:

{.experimental:"inferGenericTypes".}procproduceValue[T]:auto=default(T)leta:int=produceValue()# 'auto' cannot be inferred here

Note: The described inference does not permit the creation of overrides based on the return type of a procedure. It is a mapping mechanism that does not attempt to perform deeper inference, nor does it modify what is a valid override.

# Doesn't affect the following code, it is invalid either way{.experimental:"inferGenericTypes".}proca:int=0proca:float=1.0# Fails! Invalid code and not recommended

Sequence literals

Top-down type inference applies to sequence literals.

letx:seq[seq[float]]=@[@[1,2,3],@[4,5,6]]

This behavior is tied to the@ overloads in thesystem module, so overloading@ can disable this behavior. This can be circumvented by specifying the `` system.@ `` overload.

proc`@`(x:string):string="@"&x# does not compile:letx:seq[float]=@[1,2,3]# compiles:letx:seq[float]=system.`@`([1,2,3])

Package level objects

Every Nim module resides in a (nimble) package. An object type can be attached to the package it resides in. If that is done, the type can be referenced from other modules as anincomplete object type. This feature allows to break up recursive type dependencies across module boundaries. Incomplete object types are always passedbyref and can only be used in pointer like contexts (var/ref/ptrIncompleteObject) in general, since the compiler does not yet know the size of the object. To complete an incomplete object, thepackage pragma has to be used.package impliesbyref.

As long as a typeT is incomplete, no runtime type information forT is available.

Example:

# module A (in an arbitrary package)typePack.SomeObject=object# declare as incomplete object of package 'Pack'Triple=objecta,b,c:refSomeObject# pointers to incomplete objects are allowed# Incomplete objects can be used as parameters:procmyproc(x:SomeObject)=discard

# module B (in package "Pack")typeSomeObject*{.package.}=object# Use 'package' to complete the objects,t:stringx,y:int

This feature will likely be superseded in the future by support for recursive module dependencies.

Importing private symbols

In some situations, it may be useful to import all symbols (public or private) from a module. The syntaximportfoo{.all.} can be used to import all symbols from the modulefoo. Note that importing private symbols is generally not recommended.

See also the experimentalimportutils module.

Code reordering

The code reordering feature can implicitly rearrange procedure, template, and macro definitions along with variable declarations and initializations at the top level scope so that, to a large extent, a programmer should not have to worry about ordering definitions correctly or be forced to use forward declarations to preface definitions inside a module.

Example:

{.experimental:"codeReordering".}procfoo(x:int)=bar(x)procbar(x:int)=echo(x)foo(10)

Variables can also be reordered as well. Variables that areinitialized (i.e. variables that have their declaration and assignment combined in a single statement) can have their entire initialization statement reordered. Be wary of what code is executed at the top level:

{.experimental:"codeReordering".}proca()=echo(foo)varfoo=5a()# outputs: "5"

It is important to note that reorderingonly works for symbols at top level scope. Therefore, the following willfail to compile:

{.experimental:"codeReordering".}proca()=b()procb()=echo("Hello!")a()

This feature will likely be replaced with a better solution to remove the need for forward declarations.

Special Operators

dot operators

Nim offers a special family of dot operators that can be used to intercept and rewrite proc call and field access attempts, referring to previously undeclared symbol names. They can be used to provide a fluent interface to objects lying outside the static confines of the type system such as values from dynamic scripting languages or dynamic file formats such as JSON or XML.

When Nim encounters an expression that cannot be resolved by the standard overload resolution rules, the current scope will be searched for a dot operator that can be matched against a re-written form of the expression, where the unknown field or proc name is passed to anuntyped parameter:

a.b# becomes `.`(a, b)a.b(c,d)# becomes `.`(a, b, c, d)

The matched dot operators can be symbols of any callable kind (procs, templates and macros), depending on the desired effect:

template`.`(js:PJsonNode,field:untyped):JSON=js[astToStr(field)]varjs=parseJson("{ x: 1, y: 2}")echojs.x# outputs 1echojs.y# outputs 2

The following dot operators are available:

operator.

This operator will be matched against both field accesses and method calls.

operator.()

This operator will be matched exclusively against method calls. It has higher precedence than the. operator and this allows one to handle expressions likex.y andx.y() differently if one is interfacing with a scripting language for example.

operator.=

This operator will be matched against assignments to missing fields.

a.b=c# becomes `.=`(a, b, c)

Call operator

The call operator,(), matches all kinds of unresolved calls and takes precedence over dot operators, however it does not match missing overloads for existing routines. The experimentalcallOperator switch must be enabled to use this operator.

{.experimental:"callOperator".}template`()`(a:int,b:float):untyped=$(a,b)block:leta=1.0letb=2doAssertb(a)==`()`(b,a)doAsserta.b==`()`(b,a)block:leta=1.0procb():int=2doAssertnotcompiles(b(a))doAssertnotcompiles(a.b)# `()` not calledblock:leta=1.0procb(x:float):int=int(x+1)letc=3.0doAssertnotcompiles(a.b(c))# gives a type mismatch error same as b(a, c)doAssert(a.b)(c)==`()`(a.b,c)

Extended macro pragmas

Macro pragmas as described inthe manual can also be applied to type, variable and constant declarations.

For types:

typeMyObject{.schema:"schema.protobuf".}=object

This is translated to a call to theschema macro with annkTypeDef AST node capturing the left-hand side, remaining pragmas and the right-hand side of the definition. The macro can return either a type section or anothernnkTypeDef node, both of which will replace the original row in the type section.

In the future, thisnnkTypeDef argument may be replaced with a unary type section node containing the type definition, or some other node that may be more convenient to work with. The ability to return nodes other than type definitions may also be supported, however currently this is not convenient when dealing with mutual type recursion. For now, macros can return an unused type definition where the right-hand node is of kindnnkStmtListType. Declarations in this node will be attached to the same scope as the parent scope of the type section.

For variables and constants, it is largely the same, except a unary node with the same kind as the section containing a single definition is passed to macros, and macros can return any expression.

vara=...b{.importc,foo,nodecl.}=...c=...

Assumingfoo is a macro or a template, this is roughly equivalent to:

vara=...foo:varb{.importc,nodecl.}=...varc=...

Symbols as template/macro calls (alias syntax)

Templates and macros that have no generic parameters and no required arguments can be called as lone symbols, i.e. without parentheses. This is useful for repeated uses of complex expressions that cannot conveniently be represented as runtime values.

typeFoo=objectbar:intvarfoo=Foo(bar:10)templatebar:int=foo.barassertbar==10bar=15assertbar==15

Not nil annotation

Note: This is an experimental feature. It can be enabled with{.experimental:"notnil".}.

All types for whichnil is a valid value can be annotated with thenotnil annotation to excludenil as a valid value. Note that only local symbols are checked.

{.experimental:"notnil".}typeTObj=objectPObject=refTObjnotnilTProc=(proc(x,y:int))notnilprocp(x:PObject)=echo"not nil"# compiler catches this:p(nil)# and also this:procfoo=varx:PObjectp(x)foo()

The compiler ensures that every code path initializes variables which contain non-nilable pointers. The details of this analysis are still to be specified here.

Strict not nil checking

Note: This feature is experimental, you need to enable it with

{.experimental:"strictNotNil".}

or

nimc--experimental:strictNotNil<program>

In the second case it would check builtin and imported modules as well.

It checks the nilability of ref-like types and makes dereferencing safer based on flow typing andnotnil annotations.

Its implementation is different than thenotnil one: defined understrictNotNil. Keep in mind the difference in option names, be careful with distinguishing them.

We check several kinds of types for nilability:

• ref types
• pointer types
• proc types
• cstrings

nil

The default kind of nilability types is the nilable kind: they can have the valuenil. If you have a non-nilable typeT, you can useTnil to get a nilable type for it.

not nil

You can annotate a type where nil isn't a valid value withnotnil.

typeNilableObject=refobjecta:intObject=NilableObjectnotnilProc=(proc(x,y:int))procp(x:Object)=echox.a# ensured to dereference without an error# compiler catches this:p(nil)# and also this:varx:NilableObjectifx.isNil:p(x)else:p(x)# ok

If a type can includenil as a valid value, dereferencing values of the type is checked by the compiler: if a value which might be nil is dereferenced, this produces a warning by default, you can turn this into an error using the compiler options--warningAsError:strictNotNil.

If a type is nilable, you should dereference its values only after aisNil or equivalent check.

local turn on/off

You can still turn off nil checking on function/module level by using a{.strictNotNil:off.} pragma.

nilability state

Currently, a nilable value can beSafe,MaybeNil orNil : we use internallyParent andUnreachable but this is an implementation detail(a parent layer has the actual nilability).

• Safe means it shouldn't be nil at that point: e.g. after assignment to a non-nil value ornota.isNil check
• MaybeNil means it might be nil, but it might not be nil: e.g. an argument, a call argument or a value after anif andelse.
• Nil means it should be nil at that point; e.g. after an assignment tonil or a.isNil check.
• Unreachable means it shouldn't be possible to access this in this branch: so we do generate a warning as well.

We show an error for each dereference ([],.field,[index]() etc.) which is of a tracked expression which is inMaybeNil orNil state.

type nilability

Types are either nilable or non-nilable. When you pass a param or a default value, we use the type : for nilable types we returnMaybeNil and for non-nilableSafe.

params rules

Param's nilability is detected based on type nilability. We use the type of the argument to detect the nilability.

assignment rules

Let's say we haveleft=right.

When we assign, we pass the right's nilability to the left's expression. There should be special handling of aliasing and compound expressions which we specify in their sections. (Assignment is a possible aliasmove ormoveout).

call args rules

When we call with arguments, we have two cases when we might change the nilability.

callByVar(a)

HerecallByVar can re-assigna, so this might changea's nilability, so we change it toMaybeNil. This is also a possible aliasingmoveout (moving out of a current alias set).

call(a)

Herecall can change a field or element ofa, so if we have a dependant expression ofa : e.g.a.field. Dependants becomeMaybeNil.

branches rules

Branches are the reason we do nil checking like this: with flow checking. Sources of branching areif,while,for,and,or,case,try and combinations withreturn,break,continue andraise

We create a new layer/"scope" for each branch where we map expressions to nilability. This happens when we "fork": usually on the beginning of a construct. When branches "join" we usually unify their expression maps or/and nilabilities.

Merging usually merges maps and alias sets: nilabilities are merged like this:

templateunion(l:Nilability,r:Nilability):Nilability=## unify two statesifl==r:lelse:MaybeNil

Special handling is for.isNil and==nil, also fornot,and andor.

not reverses the nilability,and is similar to "forking" : the right expression is checked in the layer resulting from the left one andor is similar to "merging": the right and left expression should be both checked in the original layer.

isNil,==nil make expressionsNil. If there is anot or!=nil, they make themSafe. We also reverse the nilability in the opposite branch: e.g.else.

compound expressions: field, index expressions

We want to track also field(dot) and index(bracket) expressions.

We track some of those compound expressions which might be nilable as dependants of their bases:a.field is changed ifa is moved (re-assigned), similarlya[index] is dependent ona anda.field.field ona.field.

When we move the base, we update dependants toMaybeNil. Otherwise, we usually start with type nilability.

When we call args, we update the nilability of their dependants toMaybeNil as the calls usually can change them. We might need to check forstrictFuncs pure funcs and not do that then.

For field expressionsa.field, we calculate an integer value based on a hash of the tree and just accept equivalent trees as equivalent expressions.

For item expressiona[index], we also calculate an integer value based on a hash of the tree and accept equivalent trees as equivalent expressions: for static values only. For now, we support only constant indices: we don't track expression with no-const indices. For those we just report a warning even if they are safe for now: one can use a local variable to workaround. For loops this might be annoying: so one should be able to turn off locally the warning using the{.warning[StrictNotNil]:off.}.

For bracket expressions, in the future we might counta[<any>] as the same general expression. This means we should the index but otherwise handle it the same for assign (maybe "aliasing" all the non-static elements) and differentiate only for static: e.g.a[0] anda[1].

element tracking

When we assign an object construction, we should track the fields as well:

vara=Nilable(field:Nilable())# a : Safe, a.field: Safe

Usually we just track the result of an expression: probably this should apply for elements in other cases as well. Also related to tracking initialization of expressions/fields.

unstructured control flow rules

Unstructured control flow keywords asreturn,break,continue,raise mean that we jump from a branch out. This means that if there is code after the finishing of the branch, it would be run if one hasn't hit the direct parent branch of those: so it is similar to anelse. In those cases we should use the reverse nilabilities for the local to the condition expressions. E.g.

forainc:ifnota.isNil:b()breakcode# here a: Nil , because if not, we would have breaked

aliasing

We support alias detection for local expressions.

We track sets of aliased expressions. We start with all nilable local expressions in separate sets. Assignments and other changes to nilability can move / move out expressions of sets.

move: Movingleft toright means we removeleft from its current set and unify it with theright's set. This means it stops being aliased with its previous aliases.

varleft=bleft=right# moving left to right

moveout: Moving outleft might remove it from the current set and ensure that it's in its own set as a single element. e.g.

varleft=bleft=nil# moving out

warnings and errors

We show an error for each dereference ([],.field,[index]() etc.) which is of a tracked expression which is inMaybeNil orNil state.

We might also show a history of the transitions and the reasons for them that might change the nilability of the expression.

Aliasing restrictions in parameter passing

"Aliasing" here means that the underlying storage locations overlap in memory at runtime. An "output parameter" is a parameter of typevarT, an input parameter is any parameter that is not of typevar.

1. Two output parameters should never be aliased.
2. An input and an output parameter should not be aliased.
3. An output parameter should never be aliased with a global or thread local variable referenced by the called proc.
4. An input parameter should not be aliased with a global or thread local variable updated by the called proc.

One problem with rules 3 and 4 is that they affect specific global or thread local variables, but Nim's effect tracking only tracks "uses no global variable" via.noSideEffect. The rules 3 and 4 can also be approximated by a different rule:

5. A global or thread local variable (or a location derived from such a location) can only passed to a parameter of a.noSideEffect proc.

Strict funcs

Since version 1.4, a stricter definition of "side effect" is available. In addition to the existing rule that a side effect is calling a function with side effects, the following rule is also enforced:

A store to the heap via aref orptr indirection is not allowed.

For example:

{.experimental:"strictFuncs".}typeNode=refobjectle,ri:Nodedata:stringfunclen(n:Node):int=# valid: len does not have side effectsvarit=nwhileit!=nil:incresultit=it.rifuncmut(n:Node)=varit=nwhileit!=nil:it.data="yeah"# forbidden mutationit=it.ri

View types

A view type is a type that is or contains one of the following types:

• lentT (view intoT)
• openArray[T] (pair of (pointer to array ofT, size))

For example:

typeView1=openArray[byte]View2=lentstringView3=Table[openArray[char],int]

Exceptions to this rule are types constructed viaptr orproc. For example, the following types arenot view types:

typeNotView1=proc(x:openArray[int])NotView2=ptropenArray[char]NotView3=ptrarray[4,lentint]

The mutability aspect of a view type is not part of the type but part of the locations it's derived from. More on this later.

Aview is a symbol (a let, var, const, etc.) that has a view type.

Since version 1.4, Nim allows view types to be used as local variables. This feature needs to be enabled via{.experimental:"views".}.

A local variable of a view typeborrows from the locations and it is statically enforced that the view does not outlive the location it was borrowed from.

For example:

{.experimental:"views".}proctake(a:openArray[int])=echoa.lenprocmain(s:seq[int])=varx:openArray[int]=s# 'x' is a view into 's'# it is checked that 'x' does not outlive 's' and# that 's' is not mutated.foriin0..high(x):echox[i]take(x)take(x.toOpenArray(0,1))# slicing remains possiblelety=x# create a view from a viewtakey# it is checked that 'y' does not outlive 'x' and# that 'x' is not mutated as long as 'y' lives.main(@[11,22,33])

A local variable of a view type can borrow from a location derived from a parameter, another local variable, a globalconst orlet symbol or a thread-localvar orlet.

Letp the proc that is analysed for the correctness of the borrow operation.

Letsource be one of:

• A formal parameter ofp. Note that this does not cover parameters of inner procs.
• Theresult symbol ofp.
• A localvar orlet orconst ofp. Note that this does not cover locals of inner procs.
• A thread-localvar orlet.
• A globallet orconst.
• A constant array/seq/object/tuple constructor.

Path expressions

A location derived fromsource is then defined as a path expression that hassource as the owner. A path expressione is defined recursively:

• source itself is a path expression.
• Container access likee[i] is a path expression.
• Tuple accesse[0] is a path expression.
• Object field accesse.field is a path expression.
• system.toOpenArray(e,...) is a path expression.
• Pointer dereferencee[] is a path expression.
• An addressaddre is a path expression.
• A type conversionT(e) is a path expression.
• A cast expressioncast[T](e) is a path expression.
• f(e,...) is a path expression iff's return type is a view type. Because the view can only have been borrowed frome, we then know that the owner off(e,...) ise.

If a view type is used as a return type, the location must borrow from a location that is derived from the first parameter that is passed to the proc. Seethe manual for details about how this is done forvarT.

A mutable view can borrow from a mutable location, an immutable view can borrow from both a mutable or an immutable location.

If a view borrows from a mutable location, the view can be used to update the location. Otherwise it cannot be used for mutations.

Theduration of a borrow is the span of commands beginning from the assignment to the view and ending with the last usage of the view.

For the duration of the borrow operation, no mutations to the borrowed locations may be performed except via the view that borrowed from the location. The borrowed location is said to besealed during the borrow.

{.experimental:"views".}typeObj=objectfield:stringprocdangerous(s:varseq[Obj])=letv:lentObj=s[0]# seal 's's.setLen0# prevented at compile-time because 's' is sealed.echov.field

The scope of the view does not matter:

procvalid(s:varseq[Obj])=letv:lentObj=s[0]# begin of borrowechov.field# end of borrows.setLen0# valid because 'v' isn't used afterwards

The analysis requires as much precision about mutations as is reasonably obtainable, so it is more effective with the experimentalstrict funcs feature. In other words--experimental:views works better with--experimental:strictFuncs.

The analysis is currently control flow insensitive:

procinvalid(s:varseq[Obj])=letv:lentObj=s[0]iffalse:s.setLen0echov.field

In this example, the compiler assumes thats.setLen0 invalidates the borrow operation ofv even though a human being can easily see that it will never do that at runtime.

Start of a borrow

A borrow starts with one of the following:

• The assignment of a non-view-type to a view-type.
• The assignment of a location that is derived from a local parameter to a view-type.

End of a borrow

A borrow operation ends with the last usage of the view variable.

Reborrows

A viewv can borrow from multiple different locations. However, the borrow is always the full span ofv's lifetime and every location that is borrowed from is sealed duringv's lifetime.

Algorithm

The following section is an outline of the algorithm that the current implementation uses. The algorithm performs two traversals over the AST of the procedure or global section of code that uses a view variable. No fixpoint iterations are performed, the complexity of the analysis is O(N) where N is the number of nodes of the AST.

The first pass over the AST computes the lifetime of each local variable based on a notion of an "abstract time", in the implementation it's a simple integer that is incremented for every visited node.

In the second pass, information about the underlying object "graphs" is computed. Letv be a parameter or a local variable. LetG(v) be the graph thatv belongs to. A graph is defined by the set of variables that belong to the graph. Initially for allv:G(v)={v}. Every variable can only be part of a single graph.

Assignments likea=b "connect" two variables, both variables end up in the same graph{a,b}=G(a)=G(b). Unfortunately, the pattern to look for is much more complex than that and can involve multiple assignment targets and sources:

f(x, y) = g(a, b)

connectsx andy toa andb:G(x)=G(y)=G(a)=G(b)={x,y,a,b}. A type based alias analysis rules out some of these combinations, for example astring value cannot possibly be connected to aseq[int].

A pattern likev[]=value orv.field=value marksG(v) as mutated. After the second pass a set of disjoint graphs was computed.

For strict functions it is then enforced that there is no graph that is both mutated and has an element that is an immutable parameter (that is a parameter that is not of typevarT).

For borrow checking, a different set of checks is performed. Letv be the view andb the location that is borrowed from.

• The lifetime ofv must not exceedb's lifetime. Note: The lifetime of a parameter is the complete proc body.
• Ifv is used for a mutation,b must be a mutable location too.
• Duringv's lifetime,G(b) can only be modified byv (and only ifv is a mutable view).
• Ifv isresult thenb has to be a location derived from the first formal parameter or from a constant location.
• A view cannot be used for a read or a write access before it was assigned to.

Concepts

Concepts, also known as "user-defined type classes", are used to specify an arbitrary set of requirements that the matched type must satisfy.

Concepts are written in the following form:

typeComparable=conceptx,y(x<y)isboolStack[T]=concepts,varvs.pop()isTv.push(T)s.lenisOrdinalforvalueins:valueisT

The concept matches if:

1. all expressions within the body can be compiled for the tested type
2. all statically evaluable boolean expressions in the body are true
3. all type modifiers specified match their respective definitions

The identifiers following theconcept keyword represent instances of the currently matched type. You can apply any of the standard type modifiers such asvar,ref,ptr andstatic to denote a more specific type of instance. You can also apply thetype modifier to create a named instance of the type itself:

typeMyConcept=conceptx,varv,refr,ptrp,statics,typeT...

Within the concept body, types can appear in positions where ordinary values and parameters are expected. This provides a more convenient way to check for the presence of callable symbols with specific signatures:

typeOutputStream=conceptvarss.write(string)

In order to check for symbols acceptingtype params, you must prefix the type with the explicittype modifier. The named instance of the type, following theconcept keyword is also considered to have the explicit modifier and will be matched only as a type.

type# Let's imagine a user-defined casting framework with operators# such as `val.to(string)` and `val.to(JSonValue)`. We can test# for these with the following concept:MyCastables=conceptxx.to(typestring)x.to(typeJSonValue)# Let's define a couple of concepts, known from Algebra:AdditiveMonoid*=conceptx,y,typeTx+yisTT.zeroisT# require a proc such as `int.zero` or 'Position.zero'AdditiveGroup*=conceptx,y,typeTxisAdditiveMonoid-xisTx-yisT

Please note that theis operator allows one to easily verify the precise type signatures of the required operations, but since type inference and default parameters are still applied in the concept body, it's also possible to describe usage protocols that do not reveal implementation details.

Much like generics, concepts are instantiated exactly once for each tested type and any static code included within the body is executed only once.

Concept diagnostics

By default, the compiler will report the matching errors in concepts only when no other overload can be selected and a normal compilation error is produced. When you need to understand why the compiler is not matching a particular concept and, as a result, a wrong overload is selected, you can apply theexplain pragma to either the concept body or a particular call-site.

typeMyConcept{.explain.}=concept...overloadedProc(x,y,z){.explain.}

This will provide Hints in the compiler output either every time the concept is not matched or only on the particular call-site.

Generic concepts and type binding rules

The concept types can be parametric just like the regular generic types:

### matrixalgo.nimimportstd/typetraitstypeAnyMatrix*[R,C:staticint;T]=conceptm,varmvar,typeMM.ValueTypeisTM.Rows==RM.Cols==Cm[int,int]isTmvar[int,int]=TtypeTransposedType=stripGenericParams(M)[C,R,T]AnySquareMatrix*[N:staticint,T]=AnyMatrix[N,N,T]AnyTransform3D*=AnyMatrix[4,4,float]proctransposed*(m:AnyMatrix):m.TransposedType=forrin0..<m.R:forcin0..<m.C:result[r,c]=m[c,r]procdeterminant*(m:AnySquareMatrix):int=...procsetPerspectiveProjection*(m:AnyTransform3D)=...--------------### matrix.nimtypeMatrix*[M,N:staticint;T]=objectdata:array[M*N,T]proc`[]`*(M:Matrix;m,n:int):M.T=M.data[m*M.N+n]proc`[]=`*(M:varMatrix;m,n:int;v:M.T)=M.data[m*M.N+n]=v# Adapt the Matrix type to the concept's requirementstemplateRows*(M:typedesc[Matrix]):int=M.MtemplateCols*(M:typedesc[Matrix]):int=M.NtemplateValueType*(M:typedesc[Matrix]):typedesc=M.T-------------### usage.nimimportmatrix,matrixalgovarm:Matrix[3,3,int]projectionMatrix:Matrix[4,4,float]echom.transposed.determinantsetPerspectiveProjectionprojectionMatrix

When the concept type is matched against a concrete type, the unbound type parameters are inferred from the body of the concept in a way that closely resembles the way generic parameters of callable symbols are inferred on call sites.

Unbound types can appear both as params to calls such ass.push(T) and on the right-hand side of theis operator in cases such asx.popisT andx.dataisseq[T].

Unbound static params will be inferred from expressions involving the== operator and also when types dependent on them are being matched:

typeMatrixReducer[M,N:staticint;T]=conceptxx.reduce(SquareMatrix[N,T])isarray[M,int]

The Nim compiler includes a simple linear equation solver, allowing it to infer static params in some situations where integer arithmetic is involved.

Just like in regular type classes, Nim discriminates betweenbindonce andbindmany types when matching the concept. You can add thedistinct modifier to any of the otherwise inferable types to get a type that will be matched without permanently inferring it. This may be useful when you need to match several procs accepting the same wide class of types:

typeEnumerable[T]=concepteforvine:visTtypeMyConcept=concepto# this could be inferred to a type such as Enumerable[int]o.fooisdistinctEnumerable# this could be inferred to a different type such as Enumerable[float]o.barisdistinctEnumerable# it's also possible to give an alias name to a `bind many` type classtypeEnum=distinctEnumerableo.bazisEnum

On the other hand, usingbindonce types allows you to test for equivalent types used in multiple signatures, without actually requiring any concrete types, thus allowing you to encode implementation-defined types:

typeMyConcept=conceptxtypeT1=autox.foo(T1)x.bar(T1)# both procs must accept the same typetypeT2=seq[SomeNumber]x.alpha(T2)x.omega(T2)# both procs must accept the same type# and it must be a numeric sequence

As seen in the previous examples, you can refer to generic concepts such asEnumerable[T] just by their short name. Much like the regular generic types, the concept will be automatically instantiated with the bind once auto type in the place of each missing generic param.

Please note that generic concepts such asEnumerable[T] can be matched against concrete types such asstring. Nim doesn't require the concept type to have the same number of parameters as the type being matched. If you wish to express a requirement towards the generic parameters of the matched type, you can use a type mapping operator such asgenericHead orstripGenericParams within the body of the concept to obtain the uninstantiated version of the type, which you can then try to instantiate in any required way. For example, here is how one might define the classicFunctor concept from Haskell and then demonstrate that Nim'sOption[T] type is an instance of it:

importstd/[sugar,typetraits]typeFunctor[A]=conceptftypeMatchedGenericType=genericHead(typeof(f))# `f` will be a value of a type such as `Option[T]`# `MatchedGenericType` will become the `Option` typef.valisA# The Functor should provide a way to obtain# a value stored inside ittypeT=automap(f,A->T)isMatchedGenericType[T]# And it should provide a way to map one instance of# the Functor to a instance of a different type, given# a suitable `map` operation for the enclosed valuesimportstd/optionsechoOption[int]isFunctor# prints true

Concept derived values

All top level constants or types appearing within the concept body are accessible through the dot operator in procs where the concept was successfully matched to a concrete type:

typeDateTime=conceptt1,t2,typeTconstMin=T.MinDateT.NowisTt1<t2isbooltypeTimeSpan=typeof(t1-t2)TimeSpan*intisTimeSpanTimeSpan+TimeSpanisTimeSpant1+TimeSpanisTproceventsJitter(events:Enumerable[DateTime]):float=var# this variable will have the inferred TimeSpan type for# the concrete Date-like value the proc was called with:averageInterval:DateTime.TimeSpandeviation:float...

Concept refinement

When the matched type within a concept is directly tested against a different concept, we say that the outer concept is a refinement of the inner concept and thus it is more-specific. When both concepts are matched in a call during overload resolution, Nim will assign a higher precedence to the most specific one. As an alternative way of defining concept refinements, you can use the object inheritance syntax involving theof keyword:

typeGraph=conceptg,typeGofEquallyComparable,CopyabletypeVertexType=G.VertexTypeEdgeType=G.EdgeTypeVertexTypeisCopyableEdgeTypeisCopyablevarv:VertexTypee:EdgeTypeIncidendeGraph=conceptofGraph# symbols such as variables and types from the refined# concept are automatically in scope:g.source(e)isVertexTypeg.target(e)isVertexTypeg.outgoingEdges(v)isEnumerable[EdgeType]BidirectionalGraph=conceptg,typeG# The following will also turn the concept into a refinement when it# comes to overload resolution, but it doesn't provide the convenient# symbol inheritancegisIncidendeGraphg.incomingEdges(G.VertexType)isEnumerable[G.EdgeType]procf(g:IncidendeGraph)procf(g:BidirectionalGraph)# this one will be preferred if we pass a type# matching the BidirectionalGraph concept

Dynamic arguments for bindSym

This experimental feature allows the symbol name argument ofmacros.bindSym to be computed dynamically.

{.experimental:"dynamicBindSym".}importstd/macrosmacrocallOp(opName,arg1,arg2):untyped=result=newCall(bindSym($opName),arg1,arg2)echocallOp("+",1,2)echocallOp("-",5,4)

Term rewriting macros

Term rewriting macros are macros or templates that have not only aname but also apattern that is searched for after the semantic checking phase of the compiler: This means they provide an easy way to enhance the compilation pipeline with user defined optimizations:

templateoptMul{`*`(a,2)}(a:int):int=a+aletx=3echox*2

The compiler now rewritesx*2 asx+x. The code inside the curly brackets is the pattern to match against. The operators*,**,|,~ have a special meaning in patterns if they are written in infix notation, so to match verbatim against* the ordinary function call syntax needs to be used.

Term rewriting macros are applied recursively, up to a limit. This means that if the result of a term rewriting macro is eligible for another rewriting, the compiler will try to perform it, and so on, until no more optimizations are applicable. To avoid putting the compiler into an infinite loop, there is a hard limit on how many times a single term rewriting macro can be applied. Once this limit has been passed, the term rewriting macro will be ignored.

Unfortunately optimizations are hard to get right and even this tiny example iswrong:

templateoptMul{`*`(a,2)}(a:int):int=a+aprocf():int=echo"side effect!"result=55echof()*2

We cannot duplicate 'a' if it denotes an expression that has a side effect! Fortunately Nim supports side effect analysis:

templateoptMul{`*`(a,2)}(a:int{noSideEffect}):int=a+aprocf():int=echo"side effect!"result=55echof()*2# not optimized ;-)

You can make one overload matching with a constraint and one without, and the one with a constraint will have precedence, and so you can handle both cases differently.

So what about2*a? We should tell the compiler* is commutative. We cannot really do that however as the following code only swaps arguments blindly:

templatemulIsCommutative{`*`(a,b)}(a,b:int):int=b*a

What optimizers really need to do is acanonicalization:

templatecanonMul{`*`(a,b)}(a:int{lit},b:int):int=b*a

Theint{lit} parameter pattern matches against an expression of typeint, but only if it's a literal.

Parameter constraints

Theparameter constraint expression can use the operators| (or),& (and) and~ (not) and the following predicates:

Predicates that share their name with a keyword have to be escaped with backticks. Thealias andnoalias predicates refer not only to the matching AST, but also to every other bound parameter; syntactically they need to occur after the ordinary AST predicates:

templateex{a=b+c}(a:int{noalias},b,c:int)=# this transformation is only valid if 'b' and 'c' do not alias 'a':a=binca,c

Another example:

procsomefunc(s:string)=asserts=="variable"procsomefunc(s:string{nkStrLit})=asserts=="literal"procsomefunc(s:string{nkRStrLit})=asserts==r"raw"procsomefunc(s:string{nkTripleStrLit})=asserts=="""triple"""procsomefunc(s:static[string])=asserts=="constant"# Use parameter constraints to provide overloads based on both the input parameter type and form.varvariable="variable"somefunc(variable)constconstant="constant"somefunc(constant)somefunc("literal")somefunc(r"raw")somefunc("""triple""")

Pattern operators

The operators*,**,|,~ have a special meaning in patterns if they are written in infix notation.

The| operator

The| operator if used as infix operator creates an ordered choice:

templatet{0|1}():untyped=3leta=1# outputs 3:echoa

The matching is performed after the compiler performed some optimizations like constant folding, so the following does not work:

templatet{0|1}():untyped=3# outputs 1:echo1

The reason is that the compiler already transformed the 1 into "1" for theecho statement. However, a term rewriting macro should not change the semantics anyway. In fact, they can be deactivated with the--patterns:off command line option or temporarily with thepatterns pragma.

The{} operator

A pattern expression can be bound to a pattern parameter via theexpr{param} notation:

templatet{(0|1|2){x}}(x:untyped):untyped=x+1leta=1# outputs 2:echoa

The~ operator

The~ operator is the 'not' operator in patterns:

templatet{x=(~x){y}and(~x){z}}(x,y,z:bool)=x=yifx:x=zvara=falseb=truec=falsea=bandcechoa

The* operator

The* operator canflatten a nested binary expression likea&b&c to&(a,b,c):

varcalls=0proc`&&`(s:varargs[string]):string=result=s[0]foriin1..len(s)-1:result.adds[i]inccallstemplateoptConc{`&&`*a}(a:string):untyped=&&aletspace=" "echo"my"&&(space&"awe"&&"some ")&&"concat"# check that it's been optimized properly:doAssertcalls==1

The second operator of* must be a parameter; it is used to gather all the arguments. The expression"my"&&(space&"awe"&&"some ")&&"concat" is passed tooptConc ina as a special list (of kindnkArgList) which is flattened into a call expression; thus the invocation ofoptConc produces:

`&&`("my",space&"awe","some ","concat")

The** operator

The** is much like the* operator, except that it gathers not only all the arguments, but also the matched operators in reverse polish notation:

importstd/macrostypeMatrix=objectdummy:intproc`*`(a,b:Matrix):Matrix=discardproc`+`(a,b:Matrix):Matrix=discardproc`-`(a,b:Matrix):Matrix=discardproc`$`(a:Matrix):string=result=$a.dummyprocmat21():Matrix=result.dummy=21macrooptM{(`+`|`-`|`*`)**a}(a:Matrix):untyped=echotreeRepr(a)result=newCall(bindSym"mat21")varx,y,z:Matrixechox+y*z-x

This passes the expressionx+y*z-x to theoptM macro as annnkArgList node containing:

Arglist  Sym "x"  Sym "y"  Sym "z"  Sym "*"  Sym "+"  Sym "x"  Sym "-"

(This is the reverse polish notation ofx+y*z-x.)

Parameters

Parameters in a pattern are type checked in the matching process. If a parameter is of the typevarargs, it is treated specially and can match 0 or more arguments in the AST to be matched against:

templateoptWrite{write(f,x)((write|writeLine){w})(f,y)}(x,y:varargs[untyped],f:File,w:untyped)=w(f,x,y)

noRewrite pragma

Term rewriting macros and templates are currently greedy and they will rewrite as long as there is a match. There was no way to ensure some rewrite happens only once, e.g. when rewriting term to same term plus extra content.

noRewrite pragma can actually prevent further rewriting on marked code, e.g. with given exampleecho("ab") will be rewritten just once:

templatepwnEcho{echo(x)}(x:untyped)={.noRewrite.}:echo("pwned!")echo"ab"

noRewrite pragma can be useful to control term-rewriting macros recursion.

Example: Partial evaluation

The following example shows how some simple partial evaluation can be implemented with term rewriting:

procp(x,y:int;cond:bool):int=result=ifcond:x+yelse:x-ytemplateoptP1{p(x,y,true)}(x,y:untyped):untyped=x+ytemplateoptP2{p(x,y,false)}(x,y:untyped):untyped=x-y

Example: Hoisting

The following example shows how some form of hoisting can be implemented:

importstd/pegstemplateoptPeg{peg(pattern)}(pattern:string{lit}):Peg=vargl{.global,gensym.}=peg(pattern)glforiin0..3:echomatch("(a b c)",peg"'(' @ ')'")echomatch("W_HI_Le",peg"\y 'while'")

TheoptPeg template optimizes the case of a peg constructor with a string literal, so that the pattern will only be parsed once at program startup and stored in a globalgl which is then re-used. This optimization is called hoisting because it is comparable to classical loop hoisting.

AST based overloading

Parameter constraints can also be used for ordinary routine parameters; these constraints then affect ordinary overloading resolution:

procoptLit(a:string{lit|`const`})=echo"string literal"procoptLit(a:string)=echo"no string literal"constconstant="abc"varvariable="xyz"optLit("literal")optLit(constant)optLit(variable)

However, the constraintsalias andnoalias are not available in ordinary routines.

Parallel & Spawn

Nim has two flavors of parallelism:

1. Structured parallelism via theparallel statement.
2. Unstructured parallelism via the standalonespawn statement.

Nim has a builtin thread pool that can be used for CPU intensive tasks. For IO intensive tasks theasync andawait features should be used instead. Both parallel and spawn need thethreadpool module to work.

Somewhat confusingly,spawn is also used in theparallel statement with slightly different semantics.spawn always takes a call expression of the formf(a,...). LetT bef's return type. IfT isvoid, thenspawn's return type is alsovoid, otherwise it isFlowVar[T].

Within aparallel section, theFlowVar[T] is sometimes eliminated toT. This happens whenT does not contain any GC'ed memory. The compiler can ensure the location inlocation=spawnf(...) is not read prematurely within aparallel section and so there is no need for the overhead of an indirection viaFlowVar[T] to ensure correctness.

This feature is likely to be removed in the future as external packages can have better solutions.

Spawn statement

Thespawn statement can be used to pass a task to the thread pool:

importstd/threadpoolprocprocessLine(line:string)=discard"do some heavy lifting here"forxinlines("myinput.txt"):spawnprocessLine(x)sync()

For reasons of type safety and implementation simplicity the expression thatspawn takes is restricted:

• It must be a call expressionf(a,...).
• f must begcsafe.
• f must not have the calling conventionclosure.
• f's parameters may not be of typevar. This means one has to use rawptr's for data passing reminding the programmer to be careful.
• ref parameters are deeply copied, which is a subtle semantic change and can cause performance problems, but ensures memory safety. This deep copy is performed viasystem.deepCopy, so it can be overridden.
• Forsafe data exchange betweenf and the caller, a globalChannel needs to be used. However, since spawn can return a result, often no further communication is required.

spawn executes the passed expression on the thread pool and returns adata flow variableFlowVar[T] that can be read from. The reading with the^ operator isblocking. However, one can useblockUntilAny to wait on multiple flow variables at the same time:

importstd/threadpool,...# wait until 2 out of 3 servers received the update:procmain=varresponses=newSeq[FlowVarBase](3)foriin0..2:responses[i]=spawntellServer(Update,"key","value")varindex=blockUntilAny(responses)assertindex>=0responses.del(index)discardblockUntilAny(responses)

Data flow variables ensure that no data races are possible. Due to technical limitations, not every typeT can be used in a data flow variable:T has to be aref,string,seq or of a type that doesn't contain any GC'd type. This restriction is not hard to work-around in practice.

Parallel statement

Example:

# Compute pi in an inefficient wayimportstd/[strutils,math,threadpool]{.experimental:"parallel".}procterm(k:float):float=4*math.pow(-1,k)/(2*k+1)procpi(n:int):float=varch=newSeq[float](n+1)parallel:forkin0..ch.high:ch[k]=spawnterm(float(k))forkin0..ch.high:result+=ch[k]echoformatFloat(pi(5000))

The parallel statement is the preferred mechanism to introduce parallelism in a Nim program. Only a subset of the Nim language is valid within aparallel section. This subset is checked during semantic analysis to be free of data races. A sophisticateddisjoint checker ensures that no data races are possible, even though shared memory is extensively supported!

The subset is in fact the full language with the following restrictions / changes:

• spawn within aparallel section has special semantics.
• Every location of the forma[i],a[i..j] anddest wheredest is part of the patterndest=spawnf(...) has to be provably disjoint. This is called thedisjoint check.
• Every other complex locationloc that is used in a spawned proc (spawnf(loc)) has to be immutable for the duration of theparallel section. This is called theimmutability check. Currently it is not specified what exactly "complex location" means. We need to make this an optimization!
• Every array access has to be provably within bounds. This is called thebounds check.
• Slices are optimized so that no copy is performed. This optimization is not yet performed for ordinary slices outside of aparallel section.

Strict definitions andout parameters

Withexperimental:"strictDefs"every local variable must be initialized explicitly before it can be used:

{.experimental:"strictDefs".}proctest=vars:seq[string]s.add"abc"# invalid!

Needs to be written as:

{.experimental:"strictDefs".}proctest=vars:seq[string]=@[]s.add"abc"# valid!

A control flow analysis is performed in order to prove that a variable has been written to before it is used. Thus the following is valid:

{.experimental:"strictDefs".}proctest(cond:bool)=vars:seq[string]ifcond:s=@["y"]else:s=@[]s.add"abc"# valid!

In this example every path does sets to a value before it is used.

{.experimental:"strictDefs".}proctest(cond:bool)=lets:seq[string]ifcond:s=@["y"]else:s=@[]

Withexperimental:"strictDefs",let statements are allowed to not have an initial value, but every path should sets to a value before it is used.

out parameters

Anout parameter is like avar parameter but it must be written to before it can be used:

procmyopen(f:outFile;name:string):bool=f=default(File)result=open(f,name)

While it is usually the better style to use the return type in order to return results API and ABI considerations might make this infeasible. Like forvarT Nim mapsoutT to a hidden pointer. For example POSIX'sstat routine can be wrapped as:

procstat*(a1:cstring,a2:outStat):cint{.importc,header:"<sys/stat.h>".}

When the implementation of a routine with output parameters is analysed, the compiler checks that every path before the (implicit or explicit) return does set every output parameter:

procp(x:outint;y:outstring;cond:bool)=x=4ifcond:y="abc"# error: not every path initializes 'y'

Out parameters and exception handling

The analysis should take exceptions into account (but currently does not):

procp(x:outint;y:outstring;cond:bool)=x=canRaise(45)y="abc"# <-- error: not every path initializes 'y'

Once the implementation takes exceptions into account it is easy enough to useoutParam=default(typeof(outParam)) in the beginning of the proc body.

Out parameters and inheritance

It is not valid to pass an lvalue of a supertype to anoutT parameter:

typeSuperclass=objectofRootObja:intSubclass=objectofSuperclasss:stringprocinit(x:outSuperclass)=x=Superclass(a:8)varv:Subclassinitvusev.s# the 's' field was never initialized!

However, in the future this could be allowed and provide a better way to write object constructors that take inheritance into account.

Note: The implementation of "strict definitions" and "out parameters" is experimental but the concept is solid and it is expected that eventually this mode becomes the default in later versions.

Strict case objects

Withexperimental:"strictCaseObjects"every field access is checked to be valid at compile-time. The field is within acase section of anobject.

{.experimental:"strictCaseObjects".}typeFoo=objectcaseb:booloffalse:s:stringoftrue:x:intvarx=Foo(b:true,x:4)casex.boftrue:echox.x# validoffalse:echo"no"casex.boffalse:echox.x# error: field access outside of valid case branch: x.xoftrue:echo"no"

Note: The implementation of "strict case objects" is experimental but the concept is solid and it is expected that eventually this mode becomes the default in later versions.

Quirky routines

The default code generation strategy of exceptions under the ARC/ORC model is the so called--exceptions:goto implementation. This implementation inserts a check after every call that can potentially raise an exception. A typical instruction sequence for this on for a x86 64 bit machine looks like:

cmp DWORD PTR [rbx], 0je  .L1

This is a memory fetch followed by jump. (An ideal implementation would use the carry flag and a single instruction likejc .L1.)

This overhead might not be desired and depending on the semantics of the routine may not be required either. So it can be disabled via a.quirky annotation:

procwontRaise(x:int){.quirky.}=ifx!=0:# because of `quirky` this will continue even if `write` raised an IO exception:writexwontRaise(x-1)wontRaise10

If the used exception model is not--exceptions:goto then thequirky pragma has no effect and is ignored.

Thequirky pragma can also be be pushed in order to affect a group of routines and whether the compiler supports the pragma can be checked withdefined(nimHasQuirky):

whendefined(nimHasQuirky):{.pushquirky:on.}procdoRaise()=raisenewException(ValueError,"")procf():string="abc"procq(cond:bool)=ifcond:doRaise()echof()q(true)whendefined(nimHasQuirky):{.pop.}

Warning: Thequirky pragma only affects code generation, no check for validity is performed!

Threading under ARC/ORC

ARC/ORC supports a shared heap out of the box. This means that messages can be sent between threads without copies. However, without copying the data there is an inherent danger of data races. Data races are prevented at compile-time if it is enforced that onlyisolated subgraphs can be sent around.

Isolation

The standard library moduleisolation.nim provides a generic typeIsolated[T] that captures the important notion that nothing else can reference the graph that is wrapped insideIsolated[T]. It is what a channel implementation should use in order to enforce the freedom of data races:

procsend*[T](c:varChannel[T];msg:sinkIsolated[T])procrecv*[T](c:varChannel[T]):T## Note: Returns T, not Isolated[T] for convenience.procrecvIso*[T](c:varChannel[T]):Isolated[T]## remembers the data is Isolated[T].

In order to create anIsolated graph one has to use eitherisolate orunsafeIsolate.unsafeIsolate is as its name says unsafe and no checking is performed. It should be considered to be as dangerous as acast operation.

Construction must ensure that the invariant holds, namely that the wrappedT is free of external aliases into it.isolate ensures this invariant. It is inspired by Pony'srecover construct:

funcisolate(x:sinkT):Isolated[T]{.magic:"Isolate".}

As you can see, this is a new builtin because the check it performs onx is non-trivial:

IfT does not contain aref orclosure type, it is isolated. Else the syntactic structure ofx is analyzed:

• Literals likenil,4,"abc" are isolated.
• A local variable or a routine parameter is isolated if either of these conditions is true:
  1. Its type is annotated with the.sendable pragma. NoteIsolated[T] is annotated as.sendable.
  2. Its type contains the potentially dangerousref andproc{.closure} types only in places that are protected via a.sendable container.
• An array constructor[x...] is isolated if every elementx is isolated.
• An object constructorObj(x...) is isolated if every elementx is isolated.
• Anif orcase expression is isolated if all possible values the expression may return are isolated.
• A type conversionC(x) is isolated ifx is isolated. Analogous forcast expressions.
• A function callf(x...) is isolated iff is.noSideEffect and for every argumentx:
  • x is isolatedor
  • f's return type cannotaliasx's type. This is checked via a form of alias analysis as explained in the next paragraph.

Alias analysis

We start with an important, simple case that must be valid: Sending the result ofparseJson to a channel. Since the signature isfuncparseJson(input:string):JsonNode it is easy to see that JsonNode can never simply be a view intoinput which is astring.

A different case is the identity functionid,sendid(myJsonGraph) must be invalid because we do not know how many aliases intomyJsonGraph exist elsewhere.

In general typeA can alias typeT if:

• A andT are the same types.
• A is a distinct type derived fromT.
• A is a field insideT ifT is a final object type.
• T is an inheritable object type. (An inherited type could always contain afield:A).
• T is a closure type. Reason:T's environment can contain a field of typeA.
• A is the element type ofT ifT is an array, sequence or pointer type.

Sendable pragma

A container type can be marked as.sendable..sendable declares that the type encapsulates aref type effectively so that a variable of this container type can be used in anisolate context:

typeIsolated*[T]{.sendable.}=object## Isolated data can only be moved, not copied.value:Tproc`=copy`*[T](dest:varIsolated[T];src:Isolated[T]){.error.}proc`=sink`*[T](dest:varIsolated[T];src:Isolated[T]){.inline.}=# delegate to value's sink operation`=sink`(dest.value,src.value)proc`=destroy`*[T](dest:varIsolated[T]){.inline.}=# delegate to value's destroy operation`=destroy`(dest.value)

The.sendable pragma itself is an experimenal, unchecked, unsafe annotation. It is currently only used byIsolated[T].

Virtual pragma

virtual is designed to extend or create virtual functions when targeting the cpp backend. When a proc is marked with virtual, it forward declares the proc header within the type's body.

Here's an example of how to use the virtual pragma:

procnewCpp*[T]():ptrT{.importcpp:"new '*0()".}typeFoo=objectofRootObjFooPtr=ptrFooBoo=objectofFooBooPtr=ptrBooprocsalute(self:FooPtr){.virtual.}=echo"hello foo"procsalute(self:BooPtr){.virtual.}=echo"hello boo"letfoo=newCpp[Foo]()letboo=newCpp[Boo]()letbooAsFoo=cast[FooPtr](newCpp[Boo]())foo.salute()# prints hello fooboo.salute()# prints hello boobooAsFoo.salute()# prints hello boo

The virtual pragma also supports a special syntax to express Cpp constraints. Here's how it works:

$1 refers to the function name'idx refers to the type of the argument at the position idx. Where idx = 1 is thethis argument.#idx refers to the argument name.

The return type can be referred to as->'0, but this is optional and often not needed.

{.emit:"""/*TYPESECTION*/#include <iostream> class CppPrinter { public:      virtual void printConst(char* message) const {       std::cout << "Const Message: " << message << std::endl;   }   virtual void printConstRef(char* message, const int& flag) const {       std::cout << "Const Ref Message: " << message << std::endl;   }};""".}typeCppPrinter{.importcpp,inheritable.}=objectNimPrinter{.exportc.}=objectofCppPrinterprocprintConst(self:CppPrinter;message:cstring){.importcpp.}CppPrinter().printConst(message)# override is optional.procprintConst(self:NimPrinter;message:cstring){.virtual:"$1('2 #2) const override".}=echo"NimPrinter: "&$messageprocprintConstRef(self:NimPrinter;message:cstring;flag:int32){.virtual:"$1('2 #2, const '3& #3 ) const override".}=echo"NimPrinterConstRef: "&$messageNimPrinter().printConst(message)varval:int32=10NimPrinter().printConstRef(message,val)

Constructor pragma

Theconstructor pragma can be used in two ways: in conjunction withimportcpp to import a C++ constructor, and to declare constructors that operate similarly tovirtual.

Consider:

typeFoo*=objectx:int32procmakeFoo(x:int32):Foo{.constructor.}=result.x=x

It forward declares the constructor in the type definition. When the constructor has parameters, it also generates a default constructor. One can avoid this behaviour by usingnoDecl in a default constructor.

Likevirtual,constructor also supports a syntax that allows to express C++ constraints.

For example:

{.emit:"""/*TYPESECTION*/struct CppClass {  int x;  int y;  CppClass(int inX, int inY) {    this->x = inX;    this->y = inY;  }  //CppClass() = default;};""".}typeCppClass*{.importcpp,inheritable.}=objectx:int32y:int32NimClass*=objectofCppClassprocmakeNimClass(x:int32):NimClass{.constructor:"NimClass('1 #1) : CppClass(0, #1)".}=result.x=x# Optional: define the default constructor explicitlyprocmakeCppClass():NimClass{.constructor:"NimClass() : CppClass(0, 0)".}=result.x=1

In the example aboveCppClass has a deleted default constructor. Notice how by using the constructor syntax, one can call the appropriate constructor.

Notice when calling a constructor in the section of a global variable initialization, it will be called beforeNimMain meaning Nim is not fully initialized.

Constructor Initializer

By default Nim initializesimportcpp types with{}. This can be problematic when importing types with a deleted default constructor. In order to avoid this, one can specify default values for a constructor by specifying default values for the proc params in theconstructor proc.

For example:

{.emit:"""/*TYPESECTION*/struct CppStruct {  CppStruct(int x, char* y): x(x), y(y){}  int x;  char* y;};""".}typeCppStruct{.importcpp,inheritable.}=objectprocmakeCppStruct(a:cint=5,b:cstring="hello"):CppStruct{.importcpp:"CppStruct(@)",constructor.}(proc(s:CppStruct)=echo"hello")(makeCppStruct())# If one removes a default value from the constructor and passes it to the call explicitly, the C++ compiler will complain.

By usingnoInit in a type or field declaration, the compiler will skip the initializer. By doing so one can explicitly initialize those values in the constructor of the type owner.

For example:

{.emit:"""/*TYPESECTION*/  struct Foo {    Foo(int a){};  };  struct Boo {    Boo(int a){};  };    """.}typeFoo{.importcpp.}=objectBoo{.importcpp,noInit.}=objectTest{.exportc.}=objectfoo{.noInit.}:Fooboo:BooprocmakeTest():Test{.constructor:"Test() : foo(10), boo(1)".}=discardprocmain()=vart=makeTest()main()

Will produce:

structTest{Foofoo;Booboo;N_LIB_PRIVATEN_NOCONV(,Test)(void);};