Merge pull request #3395 from nanoant/patch/rename-rawsockets-to-nativesockets

Rename rawsockets module to nativesockets

16 files changed, 91 insertions, 65 deletions

diff --git a/doc/lib.txt b/doc/lib.txt
index 7c71e8ae5..3dc58eebf 100644
--- a/doc/lib.txt
+++ b/doc/lib.txt
@@ -244,7 +244,7 @@ Internet Protocols and Support
   This module implements a high-level sockets API. It will replace the
   ``sockets`` module in the future.
 
-* `rawsockets <rawsockets.html>`_
+* `nativesockets <nativesockets.html>`_
   This module implements a low-level sockets API.
 
 * `selectors <selectors.html>`_
@@ -406,6 +406,10 @@ Deprecated modules
   Use the `net <net.html>`_ or the `rawsockets <rawsockets.html>`_ module
   instead.
 
+* `rawsockets <rawsockets.html>`_
+  **Deprecated since version 0.11.4:**
+  This module has been renamed to `nativesockets <nativesockets.html>`_.
+
 
 Impure libraries
 ================
diff --git a/lib/deprecated/pure/ftpclient.nim b/lib/deprecated/pure/ftpclient.nim
index 229fe4b51..1188c0795 100644
--- a/lib/deprecated/pure/ftpclient.nim
+++ b/lib/deprecated/pure/ftpclient.nim
@@ -11,7 +11,7 @@ include "system/inclrtl"
 import sockets, strutils, parseutils, times, os, asyncio
 
 from asyncnet import nil
-from rawsockets import nil
+from nativesockets import nil
 from asyncdispatch import PFuture
 ## **Note**: This module is deprecated since version 0.11.3.
 ## You should use the async version of this module
@@ -55,7 +55,7 @@ type
     user*, pass*: string
     address*: string
     when SockType is asyncnet.AsyncSocket:
-      port*: rawsockets.Port
+      port*: nativesockets.Port
     else:
       port*: Port
 
diff --git a/lib/deprecated/pure/rawsockets.nim b/lib/deprecated/pure/rawsockets.nim
new file mode 100644
index 000000000..ee77b232e
--- /dev/null
+++ b/lib/deprecated/pure/rawsockets.nim
@@ -0,0 +1,14 @@
+import nativesockets
+export nativesockets
+
+{.warning: "rawsockets module is deprecated, use nativesockets instead".}
+
+template newRawSocket*(domain, sockType, protocol: cint): expr =
+  {.warning: "newRawSocket is deprecated, use newNativeSocket instead".}
+  newNativeSocket(domain, sockType, protocol)
+
+template newRawSocket*(domain: Domain = AF_INET,
+                       sockType: SockType = SOCK_STREAM,
+                       protocol: Protocol = IPPROTO_TCP): expr =
+  {.warning: "newRawSocket is deprecated, use newNativeSocket instead".}
+  newNativeSocket(domain, sockType, protocol)
diff --git a/lib/deprecated/pure/sockets.nim b/lib/deprecated/pure/sockets.nim
index 8fa69256b..5d6fa0078 100644
--- a/lib/deprecated/pure/sockets.nim
+++ b/lib/deprecated/pure/sockets.nim
@@ -9,7 +9,7 @@
 
 ## **Warning:** Since version 0.10.2 this module is deprecated.
 ## Use the `net <net.html>`_ or the
-## `rawsockets <rawsockets.html>`_ module instead.
+## `nativesockets <nativesockets.html>`_ module instead.
 ##
 ## This module implements portable sockets, it supports a mix of different types
 ## of sockets. Sockets are buffered by default meaning that data will be
diff --git a/lib/pure/asyncdispatch.nim b/lib/pure/asyncdispatch.nim
index 110bc6d74..7bba6bd89 100644
--- a/lib/pure/asyncdispatch.nim
+++ b/lib/pure/asyncdispatch.nim
@@ -11,7 +11,7 @@ include "system/inclrtl"
 
 import os, oids, tables, strutils, macros, times
 
-import rawsockets, net
+import nativesockets, net
 
 export Port, SocketFlag
 
@@ -475,7 +475,7 @@ when defined(windows) or defined(nimdoc):
                       addr bytesRet, nil, nil) == 0
 
   proc initAll() =
-    let dummySock = newRawSocket()
+    let dummySock = newNativeSocket()
     if not initPointer(dummySock, connectExPtr, WSAID_CONNECTEX):
       raiseOSError(osLastError())
     if not initPointer(dummySock, acceptExPtr, WSAID_ACCEPTEX):
@@ -528,7 +528,7 @@ when defined(windows) or defined(nimdoc):
                   RemoteSockaddr, RemoteSockaddrLength)
 
   proc connect*(socket: AsyncFD, address: string, port: Port,
-    domain = rawsockets.AF_INET): Future[void] =
+    domain = nativesockets.AF_INET): Future[void] =
     ## Connects ``socket`` to server at ``address:port``.
     ##
     ## Returns a ``Future`` which will complete when the connection succeeds
@@ -827,7 +827,7 @@ when defined(windows) or defined(nimdoc):
     verifyPresence(socket)
     var retFuture = newFuture[tuple[address: string, client: AsyncFD]]("acceptAddr")
 
-    var clientSock = newRawSocket()
+    var clientSock = newNativeSocket()
     if clientSock == osInvalidSocket: raiseOSError(osLastError())
 
     const lpOutputLen = 1024
@@ -900,17 +900,17 @@ when defined(windows) or defined(nimdoc):
 
     return retFuture
 
-  proc newAsyncRawSocket*(domain, sockType, protocol: cint): AsyncFD =
+  proc newAsyncNativeSocket*(domain, sockType, protocol: cint): AsyncFD =
     ## Creates a new socket and registers it with the dispatcher implicitly.
-    result = newRawSocket(domain, sockType, protocol).AsyncFD
+    result = newNativeSocket(domain, sockType, protocol).AsyncFD
     result.SocketHandle.setBlocking(false)
     register(result)
 
-  proc newAsyncRawSocket*(domain: Domain = rawsockets.AF_INET,
-               sockType: SockType = SOCK_STREAM,
-               protocol: Protocol = IPPROTO_TCP): AsyncFD =
+  proc newAsyncNativeSocket*(domain: Domain = nativesockets.AF_INET,
+                             sockType: SockType = SOCK_STREAM,
+                             protocol: Protocol = IPPROTO_TCP): AsyncFD =
     ## Creates a new socket and registers it with the dispatcher implicitly.
-    result = newRawSocket(domain, sockType, protocol).AsyncFD
+    result = newNativeSocket(domain, sockType, protocol).AsyncFD
     result.SocketHandle.setBlocking(false)
     register(result)
 
@@ -973,18 +973,18 @@ else:
     var data = PData(fd: fd, readCBs: @[], writeCBs: @[])
     p.selector.register(fd.SocketHandle, {}, data.RootRef)
 
-  proc newAsyncRawSocket*(domain: cint, sockType: cint,
-      protocol: cint): AsyncFD =
-    result = newRawSocket(domain, sockType, protocol).AsyncFD
+  proc newAsyncNativeSocket*(domain: cint, sockType: cint,
+                             protocol: cint): AsyncFD =
+    result = newNativeSocket(domain, sockType, protocol).AsyncFD
     result.SocketHandle.setBlocking(false)
     when defined(macosx):
       result.SocketHandle.setSockOptInt(SOL_SOCKET, SO_NOSIGPIPE, 1)
     register(result)
 
-  proc newAsyncRawSocket*(domain: Domain = AF_INET,
-               sockType: SockType = SOCK_STREAM,
-               protocol: Protocol = IPPROTO_TCP): AsyncFD =
-    result = newRawSocket(domain, sockType, protocol).AsyncFD
+  proc newAsyncNativeSocket*(domain: Domain = AF_INET,
+                             sockType: SockType = SOCK_STREAM,
+                             protocol: Protocol = IPPROTO_TCP): AsyncFD =
+    result = newNativeSocket(domain, sockType, protocol).AsyncFD
     result.SocketHandle.setBlocking(false)
     when defined(macosx):
       result.SocketHandle.setSockOptInt(SOL_SOCKET, SO_NOSIGPIPE, 1)
diff --git a/lib/pure/asyncnet.nim b/lib/pure/asyncnet.nim
index d7a8c3094..6b19a48be 100644
--- a/lib/pure/asyncnet.nim
+++ b/lib/pure/asyncnet.nim
@@ -56,7 +56,7 @@
 ##
 
 import asyncdispatch
-import rawsockets
+import nativesockets
 import net
 import os
 
@@ -112,8 +112,8 @@ proc newAsyncSocket*(domain: Domain = AF_INET, sockType: SockType = SOCK_STREAM,
   ##
   ## This procedure will also create a brand new file descriptor for
   ## this socket.
-  result = newAsyncSocket(newAsyncRawSocket(domain, sockType, protocol), domain,
-      sockType, protocol, buffered)
+  result = newAsyncSocket(newAsyncNativeSocket(domain, sockType, protocol),
+                          domain, sockType, protocol, buffered)
 
 proc newAsyncSocket*(domain, sockType, protocol: cint,
     buffered = true): AsyncSocket =
@@ -121,8 +121,9 @@ proc newAsyncSocket*(domain, sockType, protocol: cint,
   ##
   ## This procedure will also create a brand new file descriptor for
   ## this socket.
-  result = newAsyncSocket(newAsyncRawSocket(domain, sockType, protocol),
-      Domain(domain), SockType(sockType), Protocol(protocol), buffered)
+  result = newAsyncSocket(newAsyncNativeSocket(domain, sockType, protocol),
+                          Domain(domain), SockType(sockType),
+                          Protocol(protocol), buffered)
 
 when defined(ssl):
   proc getSslError(handle: SslPtr, err: cint): cint =
diff --git a/lib/pure/httpclient.nim b/lib/pure/httpclient.nim
index 30b838b7e..a5d4ec1a1 100644
--- a/lib/pure/httpclient.nim
+++ b/lib/pure/httpclient.nim
@@ -81,7 +81,7 @@
 
 import net, strutils, uri, parseutils, strtabs, base64, os, mimetypes, math
 import asyncnet, asyncdispatch
-import rawsockets
+import nativesockets
 
 type
   Response* = tuple[
@@ -764,10 +764,10 @@ proc newConnection(client: AsyncHttpClient, url: Uri) {.async.} =
     let port =
       if url.port == "":
         if url.scheme.toLower() == "https":
-          rawsockets.Port(443)
+          nativesockets.Port(443)
         else:
-          rawsockets.Port(80)
-      else: rawsockets.Port(url.port.parseInt)
+          nativesockets.Port(80)
+      else: nativesockets.Port(url.port.parseInt)
 
     if url.scheme.toLower() == "https":
       when defined(ssl):
diff --git a/lib/pure/rawsockets.nim b/lib/pure/nativesockets.nim
index 2d7b0e5ea..b5661c4d3 100644
--- a/lib/pure/rawsockets.nim
+++ b/lib/pure/nativesockets.nim
@@ -93,8 +93,8 @@ when useWinVersion:
     IOC_IN* = int(-2147483648)
     FIONBIO* = IOC_IN.int32 or ((sizeof(int32) and IOCPARM_MASK) shl 16) or
                              (102 shl 8) or 126
-    rawAfInet = winlean.AF_INET
-    rawAfInet6 = winlean.AF_INET6
+    nativeAfInet = winlean.AF_INET
+    nativeAfInet6 = winlean.AF_INET6
 
   proc ioctlsocket*(s: SocketHandle, cmd: clong,
                    argptr: ptr clong): cint {.
@@ -102,8 +102,8 @@ when useWinVersion:
 else:
   let
     osInvalidSocket* = posix.INVALID_SOCKET
-    rawAfInet = posix.AF_INET
-    rawAfInet6 = posix.AF_INET6
+    nativeAfInet = posix.AF_INET
+    nativeAfInet6 = posix.AF_INET6
 
 proc `==`*(a, b: Port): bool {.borrow.}
   ## ``==`` for ports.
@@ -157,12 +157,14 @@ else:
     result = cint(ord(p))
 
 
-proc newRawSocket*(domain: Domain = AF_INET, sockType: SockType = SOCK_STREAM,
-             protocol: Protocol = IPPROTO_TCP): SocketHandle =
+proc newNativeSocket*(domain: Domain = AF_INET,
+                      sockType: SockType = SOCK_STREAM,
+                      protocol: Protocol = IPPROTO_TCP): SocketHandle =
   ## Creates a new socket; returns `InvalidSocket` if an error occurs.
   socket(toInt(domain), toInt(sockType), toInt(protocol))
 
-proc newRawSocket*(domain: cint, sockType: cint, protocol: cint): SocketHandle =
+proc newNativeSocket*(domain: cint, sockType: cint,
+                      protocol: cint): SocketHandle =
   ## Creates a new socket; returns `InvalidSocket` if an error occurs.
   ##
   ## Use this overload if one of the enums specified above does
@@ -231,17 +233,17 @@ proc ntohs*(x: int16): int16 =
   when cpuEndian == bigEndian: result = x
   else: result = (x shr 8'i16) or (x shl 8'i16)
 
-proc htonl*(x: int32): int32 =
+template htonl*(x: int32): expr =
   ## Converts 32-bit integers from host to network byte order. On machines
   ## where the host byte order is the same as network byte order, this is
   ## a no-op; otherwise, it performs a 4-byte swap operation.
-  result = rawsockets.ntohl(x)
+  nativesockets.ntohl(x)
 
-proc htons*(x: int16): int16 =
+template htons*(x: int16): expr =
   ## Converts 16-bit positive integers from host to network byte order.
   ## On machines where the host byte order is the same as network byte
   ## order, this is a no-op; otherwise, it performs a 2-byte swap operation.
-  result = rawsockets.ntohs(x)
+  nativesockets.ntohs(x)
 
 proc getServByName*(name, proto: string): Servent {.tags: [ReadIOEffect].} =
   ## Searches the database from the beginning and finds the first entry for
@@ -282,7 +284,7 @@ proc getHostByAddr*(ip: string): Hostent {.tags: [ReadIOEffect].} =
 
   when useWinVersion:
     var s = winlean.gethostbyaddr(addr(myaddr), sizeof(myaddr).cuint,
-                                  cint(rawsockets.AF_INET))
+                                  cint(AF_INET))
     if s == nil: raiseOSError(osLastError())
   else:
     var s = posix.gethostbyaddr(addr(myaddr), sizeof(myaddr).Socklen,
@@ -332,9 +334,9 @@ proc getSockDomain*(socket: SocketHandle): Domain =
   if getsockname(socket, cast[ptr SockAddr](addr(name)),
                  addr(namelen)) == -1'i32:
     raiseOSError(osLastError())
-  if name.sa_family == rawAfInet:
+  if name.sa_family == nativeAfInet:
     result = AF_INET
-  elif name.sa_family == rawAfInet6:
+  elif name.sa_family == nativeAfInet6:
     result = AF_INET6
   else:
     raiseOSError(osLastError(), "unknown socket family in getSockFamily")
@@ -342,9 +344,9 @@ proc getSockDomain*(socket: SocketHandle): Domain =
 
 proc getAddrString*(sockAddr: ptr SockAddr): string =
   ## return the string representation of address within sockAddr
-  if sockAddr.sa_family == rawAfInet:
+  if sockAddr.sa_family == nativeAfInet:
     result = $inet_ntoa(cast[ptr Sockaddr_in](sockAddr).sin_addr)
-  elif sockAddr.sa_family == rawAfInet6:
+  elif sockAddr.sa_family == nativeAfInet6:
     when not useWinVersion:
       # TODO: Windows
       var v6addr = cast[ptr Sockaddr_in6](sockAddr).sin6_addr
@@ -371,7 +373,7 @@ proc getSockName*(socket: SocketHandle): Port =
   if getsockname(socket, cast[ptr SockAddr](addr(name)),
                  addr(namelen)) == -1'i32:
     raiseOSError(osLastError())
-  result = Port(rawsockets.ntohs(name.sin_port))
+  result = Port(nativesockets.ntohs(name.sin_port))
 
 proc getLocalAddr*(socket: SocketHandle, domain: Domain): (string, Port) =
   ## returns the socket's local address and port number.
@@ -388,7 +390,8 @@ proc getLocalAddr*(socket: SocketHandle, domain: Domain): (string, Port) =
     if getsockname(socket, cast[ptr SockAddr](addr(name)),
                    addr(namelen)) == -1'i32:
       raiseOSError(osLastError())
-    result = ($inet_ntoa(name.sin_addr), Port(rawsockets.ntohs(name.sin_port)))
+    result = ($inet_ntoa(name.sin_addr),
+              Port(nativesockets.ntohs(name.sin_port)))
   of AF_INET6:
     var name: Sockaddr_in6
     when useWinVersion:
@@ -404,7 +407,7 @@ proc getLocalAddr*(socket: SocketHandle, domain: Domain): (string, Port) =
     if inet_ntop(name.sin6_family.cint,
                  addr name, buf.cstring, sizeof(buf).int32).isNil:
       raiseOSError(osLastError())
-    result = ($buf, Port(rawsockets.ntohs(name.sin6_port)))
+    result = ($buf, Port(nativesockets.ntohs(name.sin6_port)))
   else:
     raiseOSError(OSErrorCode(-1), "invalid socket family in getLocalAddr")
 
@@ -423,7 +426,8 @@ proc getPeerAddr*(socket: SocketHandle, domain: Domain): (string, Port) =
     if getpeername(socket, cast[ptr SockAddr](addr(name)),
                    addr(namelen)) == -1'i32:
       raiseOSError(osLastError())
-    result = ($inet_ntoa(name.sin_addr), Port(rawsockets.ntohs(name.sin_port)))
+    result = ($inet_ntoa(name.sin_addr),
+              Port(nativesockets.ntohs(name.sin_port)))
   of AF_INET6:
     var name: Sockaddr_in6
     when useWinVersion:
@@ -439,7 +443,7 @@ proc getPeerAddr*(socket: SocketHandle, domain: Domain): (string, Port) =
     if inet_ntop(name.sin6_family.cint,
                  addr name, buf.cstring, sizeof(buf).int32).isNil:
       raiseOSError(osLastError())
-    result = ($buf, Port(rawsockets.ntohs(name.sin6_port)))
+    result = ($buf, Port(nativesockets.ntohs(name.sin6_port)))
   else:
     raiseOSError(OSErrorCode(-1), "invalid socket family in getLocalAddr")
 
diff --git a/lib/pure/net.nim b/lib/pure/net.nim
index 00a6c0c92..d1016011e 100644
--- a/lib/pure/net.nim
+++ b/lib/pure/net.nim
@@ -10,7 +10,7 @@
 ## This module implements a high-level cross-platform sockets interface.
 
 {.deadCodeElim: on.}
-import rawsockets, os, strutils, unsigned, parseutils, times
+import nativesockets, os, strutils, unsigned, parseutils, times
 export Port, `$`, `==`
 
 const useWinVersion = defined(Windows) or defined(nimdoc)
@@ -145,7 +145,7 @@ proc newSocket*(domain, sockType, protocol: cint, buffered = true): Socket =
   ## Creates a new socket.
   ##
   ## If an error occurs EOS will be raised.
-  let fd = newRawSocket(domain, sockType, protocol)
+  let fd = newNativeSocket(domain, sockType, protocol)
   if fd == osInvalidSocket:
     raiseOSError(osLastError())
   result = newSocket(fd, domain.Domain, sockType.SockType, protocol.Protocol,
@@ -156,7 +156,7 @@ proc newSocket*(domain: Domain = AF_INET, sockType: SockType = SOCK_STREAM,
   ## Creates a new socket.
   ##
   ## If an error occurs EOS will be raised.
-  let fd = newRawSocket(domain, sockType, protocol)
+  let fd = newNativeSocket(domain, sockType, protocol)
   if fd == osInvalidSocket:
     raiseOSError(osLastError())
   result = newSocket(fd, domain, sockType, protocol, buffered)
@@ -354,7 +354,7 @@ proc listen*(socket: Socket, backlog = SOMAXCONN) {.tags: [ReadIOEffect].} =
   ## queue of pending connections.
   ##
   ## Raises an EOS error upon failure.
-  if rawsockets.listen(socket.fd, backlog) < 0'i32:
+  if nativesockets.listen(socket.fd, backlog) < 0'i32:
     raiseOSError(osLastError())
 
 proc bindAddr*(socket: Socket, port = Port(0), address = "") {.
diff --git a/tests/async/tasyncawait.nim b/tests/async/tasyncawait.nim
index e5895abe1..443f769cd 100644
--- a/tests/async/tasyncawait.nim
+++ b/tests/async/tasyncawait.nim
@@ -2,7 +2,7 @@ discard """
   file: "tasyncawait.nim"
   output: "5000"
 """
-import asyncdispatch, rawsockets, net, strutils, os
+import asyncdispatch, nativesockets, net, strutils, os
 
 var msgCount = 0
 
@@ -18,7 +18,7 @@ proc sendMessages(client: TAsyncFD) {.async.} =
 
 proc launchSwarm(port: TPort) {.async.} =
   for i in 0 .. <swarmSize:
-    var sock = newAsyncRawSocket()
+    var sock = newAsyncNativeSocket()
 
     await connect(sock, "localhost", port)
     await sendMessages(sock)
@@ -38,7 +38,7 @@ proc readMessages(client: TAsyncFD) {.async.} =
         doAssert false
 
 proc createServer(port: TPort) {.async.} =
-  var server = newAsyncRawSocket()
+  var server = newAsyncNativeSocket()
   block:
     var name: Sockaddr_in
     when defined(windows):
diff --git a/tests/async/tasyncconnect.nim b/tests/async/tasyncconnect.nim
index b27a810b8..3dac379b2 100644
--- a/tests/async/tasyncconnect.nim
+++ b/tests/async/tasyncconnect.nim
@@ -19,7 +19,7 @@ when defined(windows) or defined(nimdoc):
     quit("Error: unhandled exception: Connection refused")
 else:
     proc testAsyncConnect() {.async.} =
-        var s = newAsyncRawSocket()
+        var s = newAsyncNativeSocket()
 
         await s.connect(testHost, testPort)
 
diff --git a/tests/async/tasynceverror.nim b/tests/async/tasynceverror.nim
index 2f570344f..22b4fe9a7 100644
--- a/tests/async/tasynceverror.nim
+++ b/tests/async/tasynceverror.nim
@@ -7,7 +7,7 @@ discard """
 import
     asyncdispatch,
     asyncnet,
-    rawsockets,
+    nativesockets,
     os
 
 
@@ -21,7 +21,7 @@ when defined(windows) or defined(nimdoc):
     quit("Error: unhandled exception: Connection reset by peer")
 else:
     proc createListenSocket(host: string, port: Port): TAsyncFD =
-        result = newAsyncRawSocket()
+        result = newAsyncNativeSocket()
 
         SocketHandle(result).setSockOptInt(SOL_SOCKET, SO_REUSEADDR, 1)
 
diff --git a/tests/cpp/trawsockets.nim b/tests/cpp/tnativesockets.nim
index bc129de57..6108380a8 100644
--- a/tests/cpp/trawsockets.nim
+++ b/tests/cpp/tnativesockets.nim
@@ -2,4 +2,4 @@ discard """
   cmd: "nim cpp $file"
 """
 
-import rawsockets
+import nativesockets
diff --git a/tests/macros/tgensym.nim b/tests/macros/tgensym.nim
index b3aef0a2c..a4d1a3606 100644
--- a/tests/macros/tgensym.nim
+++ b/tests/macros/tgensym.nim
@@ -1,6 +1,6 @@
-import rawsockets, asyncdispatch, macros
+import nativesockets, asyncdispatch, macros
 var p = newDispatcher()
-var sock = newAsyncRawSocket()
+var sock = newAsyncNativeSocket()
 
 proc convertReturns(node, retFutureSym: NimNode): NimNode {.compileTime.} =
   case node.kind
diff --git a/tests/modules/texport.nim b/tests/modules/texport.nim
index 0890fb369..a8c217ab8 100644
--- a/tests/modules/texport.nim
+++ b/tests/modules/texport.nim
@@ -5,7 +5,7 @@ discard """
 import mexporta
 
 # bug #1029:
-from rawsockets import accept
+from nativesockets import accept
 
 # B.TMyObject has been imported implicitly here:
 var x: TMyObject
diff --git a/web/news.txt b/web/news.txt
index 33ceac49e..2b6079620 100644
--- a/web/news.txt
+++ b/web/news.txt
@@ -9,6 +9,9 @@ News
   Changes affecting backwards compatibility
   -----------------------------------------
 
+  - The ``rawsockets`` module has been renamed to ``nativesockets`` to avoid
+    confusion with TCP/IP raw sockets, so ``newNativeSocket`` should be used
+    instead of ``newRawSocket``.
   - The ``miliseconds`` property of ``times.TimeInterval`` is now ``milliseconds``.
     Code accessing that property is deprecated and code using ``miliseconds``
     during object initialization or as a named parameter of ``initInterval()``