Skip to content

Commit

Permalink
docs: Code blocks had 3 space indentation and other anomalies (#3777)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ekrich
ekrich committed Feb 17, 2024
1 parent e40b901 commit 9d169f8
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 73 deletions.
38 changes: 19 additions & 19 deletions docs/lib/javalib.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -696,9 +696,9 @@ For that to work, you have to specify an additional NativeConfig option:

.. code-block:: scala
nativeConfig ~= {
_.withEmbedResources(true)
}
nativeConfig ~= {
_.withEmbedResources(true)
}
This will include the resource files found on the classpath in the resulting
binary file.
Expand All @@ -712,11 +712,11 @@ The example below will include all the text and png files in the classpath, whil

.. code-block:: scala
nativeConfig ~= {
_.withEmbedResources(true)
.withResourceIncludePatterns(Seq("**.txt", "**.png"))
.withResourceExcludePatterns(Seq("rootdoc.txt"))
}
nativeConfig ~= {
_.withEmbedResources(true)
.withResourceIncludePatterns(Seq("**.txt", "**.png"))
.withResourceExcludePatterns(Seq("rootdoc.txt"))
}
Also, note that this featuer is using Java's PathMatcher, which behave a bit different from the posix glob. https://docs.oracle.com/javase/tutorial/essential/io/find.html

Expand Down Expand Up @@ -785,20 +785,20 @@ allowing to load only requested implementation based on provided configuration.

.. code-block:: scala
nativeConfig ~= { _.withServiceProviders(
Map(
"MyServiceName" -> Seq("MyImplementation1", "foo.bar.MyOtherImplementation",
"java.nio.file.spi.FileSystemProvider" -> Seq("my.lib.MyCustomFileSystem"))
)
)}
nativeConfig ~= { _.withServiceProviders(
Map(
"MyServiceName" -> Seq("MyImplementation1", "foo.bar.MyOtherImplementation",
"java.nio.file.spi.FileSystemProvider" -> Seq("my.lib.MyCustomFileSystem"))
)
)}
All providers of service referenced by ``java.util.ServiceLoader.load`` that were reached from any of entrypoints, would be enlisted when linking.
The providers might have 1 out 5 available statuses:
* ``Loaded`` - this provider was allowed by the config and found on the classpath. It would be available at runtime.
* ``Available`` - this provider was found on classpath, but it was not enlisted in the config. It would not be available at runtime.
* ``UnknownConfigEntry`` - provider enlisted in config was not found on classpath. It might suggest typo in configuration or in ``META-INF/servies`` file.
* ``NotFoundOnClasspath`` - given provider was found both in config and in ``META-INF/services`` file, but it was not found on classpath. It might suggest that given provider was not cross-compiled for Scala Native.
* ``NoProviders`` - status assigned for services without any available implementations found on classpath and without config entries
* ``Loaded`` - this provider was allowed by the config and found on the classpath. It would be available at runtime.
* ``Available`` - this provider was found on classpath, but it was not enlisted in the config. It would not be available at runtime.
* ``UnknownConfigEntry`` - provider enlisted in config was not found on classpath. It might suggest typo in configuration or in ``META-INF/servies`` file.
* ``NotFoundOnClasspath`` - given provider was found both in config and in ``META-INF/services`` file, but it was not found on classpath. It might suggest that given provider was not cross-compiled for Scala Native.
* ``NoProviders`` - status assigned for services without any available implementations found on classpath and without config entries


Continue to :ref:`libc`.
109 changes: 55 additions & 54 deletions docs/user/interop.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,20 +130,21 @@ list type (i.e. ``va_list``), and partially for ``...`` varargs. For example ``v
defined in C as:

.. code-block:: C
int vprintf(const char * format, va_list arg);
int printf(const char * format, ... );
int vprintf(const char * format, va_list arg);
int printf(const char * format, ... );
can be declared in Scala as:

.. code-block:: scala
import scala.scalanative.unsafe._
import scala.scalanative.unsafe._
@extern
object mystdio {
def vprintf(format: CString, args: CVarArgList): CInt = extern
def printf(format: CString, args: Any*): CInt = extern
}
@extern
object mystdio {
def vprintf(format: CString, args: CVarArgList): CInt = extern
def printf(format: CString, args: Any*): CInt = extern
}
The limitation of `...` interop requires that it's arguments needs to passed directly to variadic arguments function or arguments need to be inlined.
This is required to obtain enough information on how arguments show be passed in regards to C ABI.
Expand All @@ -153,20 +154,20 @@ For ``va_list`` interop, one can wrap a function in a nicer API like:

.. code-block:: scala
import scala.scalanative.unsafe._
import scala.scalanative.unsafe._
def myprintf(format: CString, args: CVarArg*): CInt =
Zone {
mystdio.vprintf(format, toCVarArgList(args.toSeq))
}
def myprintf(format: CString, args: CVarArg*): CInt =
Zone {
mystdio.vprintf(format, toCVarArgList(args.toSeq))
}
See `Memory management`_ for a guide of using ``unsafe.Zone``
And then call it just like a regular Scala function:

.. code-block:: scala
myprintf(c"2 + 3 = %d, 4 + 5 = %d", 2 + 3, 4 + 5)
printf(c"2 + 3 = %d, 4 + 5 = %d", 2 + 3, 4 + 5)
myprintf(c"2 + 3 = %d, 4 + 5 = %d", 2 + 3, 4 + 5)
printf(c"2 + 3 = %d, 4 + 5 = %d", 2 + 3, 4 + 5)
Exported methods
----------------
Expand Down Expand Up @@ -290,19 +291,19 @@ from the corresponding companion object.

.. code-block:: scala
import scalanative.unsafe.CFuncPtr0
def myFunc(): Unit = println("hi there!")
import scalanative.unsafe.CFuncPtr0
def myFunc(): Unit = println("hi there!")
val myFuncPtr: CFuncPtr0[Unit] = CFuncPtr0.fromScalaFunction(myFunc)
val myImplFn: CFuncPtr0[Unit] = myFunc _
val myLambdaFuncPtr: CFuncPtr0[Unit] = () => println("hello!")
val myFuncPtr: CFuncPtr0[Unit] = CFuncPtr0.fromScalaFunction(myFunc)
val myImplFn: CFuncPtr0[Unit] = myFunc _
val myLambdaFuncPtr: CFuncPtr0[Unit] = () => println("hello!")
On Scala 2.12 or newer, the Scala language automatically converts
from closures to SAM types:

.. code-block:: scala
val myfuncptr: unsafe.CFuncPtr0[Unit] = () => println("hi there!")
val myfuncptr: unsafe.CFuncPtr0[Unit] = () => println("hi there!")
Memory management
`````````````````
Expand All @@ -312,23 +313,23 @@ runtime system, one has to be extra careful when working with unmanaged memory.

1. **Zone allocation.** (since 0.3)

Zones (also known as memory regions/contexts) are a technique for
semi-automatic memory management. Using them one can bind allocations
to a temporary scope in the program and the zone allocator will
automatically clean them up for you as soon as execution goes out of it:
Zones (also known as memory regions/contexts) are a technique for
semi-automatic memory management. Using them one can bind allocations
to a temporary scope in the program and the zone allocator will
automatically clean them up for you as soon as execution goes out of it:

.. code-block:: scala
.. code-block:: scala
import scala.scalanative.unsafe._
import scala.scalanative.unsafe._
// For Scala 3
Zone {
val buffer = alloc[Byte](n)
}
// For Scala 2, works, but is not idiomatic on Scala 3
Zone.acquire { implicit z =>
val buffer = alloc[Byte](n)
}
// For Scala 3
Zone {
val buffer = alloc[Byte](n)
}
// For Scala 2, works, but is not idiomatic on Scala 3
Zone.acquire { implicit z =>
val buffer = alloc[Byte](n)
}
``alloc`` requests memory sufficient to contain `n` values of a given type.
If number of elements is not specified, it defaults to a single element.
Expand All @@ -348,34 +349,34 @@ runtime system, one has to be extra careful when working with unmanaged memory.

2. **Stack allocation.**

Scala Native provides a built-in way to perform stack allocations of
using ``unsafe.stackalloc`` function:
Scala Native provides a built-in way to perform stack allocations of
using ``unsafe.stackalloc`` function:

.. code-block:: scala
.. code-block:: scala
val buffer = unsafe.stackalloc[Byte](256)
val buffer = unsafe.stackalloc[Byte](256)
This code will allocate 256 bytes that are going to be available until
the enclosing method returns. Number of elements to be allocated is optional
and defaults to 1 otherwise. Memory **is zeroed out** by default.
This code will allocate 256 bytes that are going to be available until
the enclosing method returns. Number of elements to be allocated is optional
and defaults to 1 otherwise. Memory **is zeroed out** by default.

When using stack allocated memory one has to be careful not to capture
this memory beyond the lifetime of the method. Dereferencing stack allocated
memory after the method's execution has completed is undefined behavior.
When using stack allocated memory one has to be careful not to capture
this memory beyond the lifetime of the method. Dereferencing stack allocated
memory after the method's execution has completed is undefined behavior.

3. **Manual heap allocation.**

Scala Native's library contains a bindings for a subset of the standard
libc functionality. This includes the trio of ``malloc``, ``realloc`` and
``free`` functions that are defined in ``unsafe.stdlib`` extern object.
Scala Native's library contains a bindings for a subset of the standard
libc functionality. This includes the trio of ``malloc``, ``realloc`` and
``free`` functions that are defined in ``unsafe.stdlib`` extern object.

Calling those will let you allocate memory using system's standard
dynamic memory allocator. Every single manual allocation must also
be freed manually as soon as it's not needed any longer.
Calling those will let you allocate memory using system's standard
dynamic memory allocator. Every single manual allocation must also
be freed manually as soon as it's not needed any longer.

Apart from the standard system allocator one might
also bind to plethora of 3-rd party allocators such as jemalloc_ to
serve the same purpose.
Apart from the standard system allocator one might
also bind to plethora of 3-rd party allocators such as jemalloc_ to
serve the same purpose.

.. Comment - https does not work with jemalloc.net
.. _jemalloc: http://jemalloc.net/
Expand Down

0 comments on commit 9d169f8

Please sign in to comment.