Running Concurnas Programs?

Table of Contents

Running Concurnas Programs

Compiled programs written in Concurnas may be executed via the conc tool. For example, in conjunction with the concc tool for compilation:

Using example code, hello.conc:

System.out.println("Hello World!")

We can compile and execute this as follows:

D:\work\bin>concc hello.conc
D:\work\bin>conc hello
Hello World!
D:\work\bin>

The syntax for the conc tool is as follows:

conc options* entryPoint? cmdLineArguments*

Let us now look in detail at what is taking place above:

Running code with Concurnas?

Compiled Concurnas code can be run with Concurnas via the conc command which comes as standard as part of the Concurnas distribution. We can also run conc in interactive Read-Evaluate-Print Loop (REPL) mode, this is explored in the REPL chapter. Here we focus upon non-interactive execution of pre compiled code. If conc has not been added to the path (the default during installation), the tool may be started from within that directory. If Concurnas has not already completed its installation for the detected JDK which it is being run under, it will first complete that process (this may take a few minutes).

We use the conc command with an entry-point class or jar file reference in order to start conc in non-interactive execution mode:

D:\work>conc myClass
D:\work>conc myClass.class
D:\work>conc myJar
D:\work>conc myJar.jar

A full list of optional options for conc is found under the Command line options section.

Bootstrapping Code?

In order to run a program with Concurnas via the conc tool we must pass an entry-point class or jar file reference. For a jar file to be used in this manner it requires a class within it to be nominated as its entry point. This entry point reference is then examined and one of the following is executed in order of precedence:

def main(args String[]) ANY_TYPE
def main() ANY_TYPE
Top level code

We see above that specifying a main method within our entry-point class is not a requirement, and if one is not defined then this will result in any top level code of the class file being invoked upon execution instead. However, using a main method is recommended in cases where we wish to use a referenced piece of code as both a library and program. This is because, where the code within the .class file is used like a library, upon first execution of something imported from that library class, all the top level code will be executed, including our code we wish to execute as a program - something which is rarely desirable. An explicit main method on the other hand must be explicitly invoked, thus avoiding this problem.

The main method declaration may return a value of any type. The .toString() method will be called on the returned value and will be output to stdout (the console). If null is returned then 'null' will be output.

If the main method declaration returns an int this will not be output but will rather be used as the exit code of the program itself. Note that the expectation on POSIX systems is that an exit code of 0 indicates successful execution, with any number from 1 to 255 indicating a specific failure case.

The main method declaration will receive any command line parameters passed to the program upon execution if its signature is declared as: def main(args String[]) ANY_TYPE.

Command line options?

There can be zero to many options specified on a call to conc:

-classpath path or -cp path: The classpath option enables one to override the CLASSPATH environment variable. Elements are delimited via ; and must be surrounded by "" under Unix based operating systems. Elements may consist of directories, .class file references or .jar file references.
-s: Server mode. When running in non interactive mode (i.e an entry point is provided) Concurnas will not terminate the process upon the entry point main method (or alternative) completing execution.
-bc: Print bytecode. This option is applicable when running in REPL mode. Print the bytecode generated from the provided input.
-J: JVM argument. Prefix jvm arguments with -J in order to pass them to the underlying JVM. e.g. -J-Xms2G -J-Xmx5G.
-D: System property. Prefix system properties with -D in order to pass them to the underlying JVM. e.g. -Dcom.mycompany.mysetting=108.
--help: List documentation for options above.

Examples?

Single file programs?

We can compile and execute our simple hello world (named littlehello.conc) as follows:

D:\work>concc littlehello.conc
Finished compilation of: D:\work\littlehello.conc -> D:\work\littlehello.class [littlehello]

D:\work>conc littlehello
hello world

D:\work>

In practice it is very rare that we will write single file programs.

Multi file programs?

Lets take a slightly more involved hello world example (named hello.conc) which compiles into multiple class files thus requiring us to make of the classpath argument:

class SayHello{
  def do(args String[]){
    System.err.println("hello world received args: "+ args)
  }
}

def main(args String[]){
  new SayHello().do(args)
}

We can compile and execute this code as follows:

D:\work>concc hello.conc
Finished compilation of: D:\work\hello.conc -> D:\work\hello$SayHello.class [hello$SayHello], D:\work\hello.class [hello]

D:\work>conc -cp ./ hello
hello world got args: null

D:\work>

Notice above that we must make use of the -cp argument in order to specify the current directory as holding both our entry point class: hello.class and supporting SayHello class: hello$SayHello.class.

Note that whilst it is best practice to specify a -cp argument, in the above case it may be omitted as Concurnas will automatically add the current directory to the classpath in instances where no -cp argument is provided and the entry class is within the current working directory¹:

D:\work>conc hello
hello world got args: null

D:\work>

We can pass command line arguments to our hello world class since its main method takes a String array argument:

D:\work>conc -cp ./ hello there
hello world got args: [there]

D:\work>

Multi file programs in jar's?

In practice it is often most convenient for the purposes of software distribution and organization, to package code up within jar's, these can be executed via the use of the -jar argument as illustrated here. Let's take our hello.conc we previously implemented:

D:\work>concc -jar helloWorld[hello] hello.conc
Finished compilation of: D:\work\hello.conc -> D:\work\hello$SayHello.class [hello$SayHello], D:\work\hello.class [hello]

D:\work>conc helloWorld.jar
hello world got args: null

D:\work>conc helloWorld.jar there
hello world got args: [there]

D:\work>

Running programs in server mode?

Normally, when running in non-interactive mode (i.e an entry point is provided) Concurnas will terminate the process upon the entry point main method (or alternative) completing execution. To suppress this behaviour, for instance, for a server application, we use the -s argument as follows:

D:\work>conc -s helloWorld.jar there
hello world got args: [there]

The above program will not terminate until it receives as a kill signal from the operating system.

Terminating Code?

If we are running a Concurnas application in server mode (as par above) it can often be useful to register shutdown handlers. These are invoked upon receiving a SIGTERM signal from the operating system (check your operating system documentation for details on how to do this). More details on shutdown handlers can be found in the shutdown handlers section.

Starting conc in interactive REPL mode?

The conc tool has the ability to run compiled Concurnas code as we have seen in this chapter. It also has the ability to run in interactive REPL mode. More information about running in interactive REPL mode can be found in the The Concurnas REPL section.

JVM arguments?

Arguments (for example garbage collection and memory allocation tuning) may be applied to the underlying JVM executing conc by prefixing them with -J. For example:

D:\work>conc -J-Xmx2g helloWorld.jar there
hello world got args: [there]

D:\work>

System properties?

System properties may be specified on the command line when running conc by prefixing them with -D. For example:

D:\work>conc -Dcom.mycompany.mysetting=108 helloWorld.jar there
hello world got args: [there]

D:\work>

Adding conc to the path?

It is recommended that the <installDir>/bin be added to the system path in order to permit /conc to be run from any directory. Check your operating system documentation for details of how to do this. The Windows installer for Concurnas will perform this automatically, as will installation via the SDKMAN! platform.

Notes?

The first time the conc tool is executed, or when a new JVM environment upon which is its being executed is detected, an 'installation' will take place wherein Concurnas will set itself up to execute efficiently upon said JVM environment by caching a copy of the JDK. This can take up to a few minutes to complete.

Footnotes

¹This feature has been added so as to aid newcomers to the programming language