Skip to content

Commit 378e542

Browse files
authored
Merge pull request #224 from lf-lang/single-threaded-rebased
Changes regarding `single-threaded` target property
2 parents 28e4370 + 6620b1e commit 378e542

File tree

1 file changed

+16
-19
lines changed

1 file changed

+16
-19
lines changed

docs/reference/target-declaration.mdx

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Every Lingua Franca program begins with a statement of this form:
1717
target <name> <parameters>
1818
```
1919

20-
The `<name>` gives the name of some Lingua Franca target language, which is the language in which reactions are written. This is also the language of the program(s) generated by the Lingua Franca compiler. The target languages currently supported are C, C++, Python, TypeScript, and Rust.
20+
The `<name>` gives the name of some Lingua Franca target language, which is the language in which reactions are written. This is also the language of the program(s) generated by the Lingua Franca compiler. The target languages currently supported are C, C++, Python, TypeScript, and Rust. There is also a target CCpp that is just like the C target except that it uses a C++ compiler to compile the code, thereby allowing inclusion of C++ code.
2121

2222
# Summary of Parameters
2323

@@ -45,7 +45,7 @@ A target specification may have optional parameters, the names and values of whi
4545
- [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
4646
- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
4747
- [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
48-
- [**threading**](#threading): Whether to use multiple threads.
48+
- [**single-threaded**](#single-threaded): Specify to not use multithreading.
4949
- [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
5050
- [**workers**](#workers): If using multiple threads, how many worker threads to create.
5151

@@ -67,7 +67,7 @@ c={
6767
logging: <error, warning, info, log, debug>,
6868
no-compile: <true or false>,
6969
protobufs: <string or list of strings>,
70-
threading: <true or false>,
70+
single-threaded: <true or false>,
7171
timeout: <time>,
7272
workers: <non-negative integer>,
7373
};`
@@ -95,7 +95,7 @@ py={
9595
logging: <error, warning, info, log, debug>,
9696
no-compile: <true or false>,
9797
protobufs: <string or list of strings>,
98-
threading: <true or false>,
98+
single-threaded: <true or false>,
9999
timeout: <time>,
100100
workers: <non-negative integer>,
101101
};`
@@ -108,6 +108,7 @@ rs={
108108
export-dependency-graph: <true or false>,
109109
rust-include: <array of strings>,
110110
single-file-project: <true or false>,
111+
single-threaded: <true or false>,
111112
timeout: <time value>,
112113
}`
113114
}
@@ -636,23 +637,20 @@ If true, enables [single-file project layout](#single-file-layout).
636637
</ShowIf>
637638
</ShowIfs>
638639

639-
## threading
640+
## single-threaded
640641

641642
<ShowIfs>
642643
<ShowIf cpp ts >
643-
This target does not support the `threading` target option.
644+
This target does not support the `single-threaded` target option.
644645
</ShowIf>
645646
<ShowIf c>
646-
If threading is disabled (by setting `threading` to `false`), then no thread library is used, and the `lf_schedule()` function is not thread safe. This setting is incompatible with asynchronously scheduling any physical actions and hence this parameter will be ignored for programs that have physical actions.
647-
See [workers](#workers).
647+
If threading is disabled (by setting `single-threaded` to `true`), then no thread library is used. This is mostly useful for bare-metal embedded software implementations where no thread library is available. In such a setting, mutual exclusion is typically implemented by disabling interrupts.
648648
</ShowIf>
649649
<ShowIf py>
650650
The Python target uses the single threaded C runtime by default but will switch to the multithreaded C runtime if a physical action is detected. This target property can be used to override this behavior.
651651
</ShowIf>
652652
<ShowIf rs>
653-
Boolean flag (either `true` (default) or `false`) that controls if the project is to be compiled with support for multi-threading.
654-
655-
See [workers](#workers).
653+
If the target property `single-threaded` is set to `true`, the project will be compiled without support for multi-threading; support for multi-threading is enabled by default.
656654
</ShowIf>
657655
</ShowIfs>
658656

@@ -667,9 +665,7 @@ A time value (with units) specifying the logical stop time of execution. See [Te
667665
This target does not support the `workers` target option.
668666
</ShowIf>
669667
<ShowIf c>
670-
This parameter takes a non-negative integer and specifies the number of worker threads to execute the generated program. If threading is turned on (the default, see [threading](#threading)), then the generated code will use a target platform thread library and generate multi-threaded code. This can transparently execute reactions that have no dependence on one another in parallel on multiple cores. By default, threading is turned on, and the `workers` property is set to `0`, which means that the number of workers is determined by the runtime system. Typically, it will be set to the number of cores on the machine running the code. To use a different number of worker threads, give a positive integer for this target parameter.
671-
672-
With value `0`, the runtime engine is free to choose the number of worker threads to use. Typically, this will equal the number of hardware threads on the machine on which the Lingua Franca code generator is run.
668+
This parameter takes a non-negative integer and specifies the number of worker threads to execute the generated program. Unless the `single-threaded` target property is set to `true` on (see [single-threaded](#single-threaded)), the generated code will use a target platform thread library and generate multithreaded code. This can transparently execute reactions that have no dependence on one another in parallel on multiple cores. By default, `single-threaded` set to `false`, and the `workers` property is set to `0`, which means that the number of workers is determined by the runtime system. Typically, it will be set to the number of cores on the machine running the code. To use a different number of worker threads, give a positive integer for this target parameter.
673669
</ShowIf>
674670
<ShowIf cpp>
675671
This parameter takes a non-negative integer and specifies the number of worker threads to execute the generated program. With value `0` (the default), the runtime engine is free to choose the number of worker threads to use. In the $target-language$ target, the runtime system will determine the number of hardware threads on the machine on which the program is run and set the number of worker threads equal to that number.
@@ -688,14 +684,15 @@ This parameter takes a non-negative integer and specifies the number of worker t
688684

689685
<ShowIfs>
690686
<ShowIf ts >
691-
In the TypeScript target, the generated JavaScript program understands the following command-line arguments, each of which has a short form (one character) and a long form:
687+
In the TypeScript target, the generated JavaScript program understands the following command-line arguments, most of which have a short form (one character) and a long form:
692688

693-
- `-f, --fast [true | false]`: Specifies whether to wait for physical time to match logical time. The default is `false`. If this is `true`, then the program will execute as fast as possible, letting logical time advance faster than physical time.
694-
- `-o, --timeout '<duration> <units>'`: Stop execution when logical time has advanced by the specified _duration_. The units can be any of nsec, usec, msec, sec, minute, hour, day, week, or the plurals of those. For the duration and units of a timeout argument to be parsed correctly as a single value, these should be specified in quotes with no leading or trailing space (e.g. '5 sec').
689+
- `-f, --fast [true | false]`: Specify whether to allow logical time to progress faster than physical time. The default is `false`. If this is `true`, then the program will execute as fast as possible, letting logical time advance faster than physical time.
690+
- `-h, --help`: Print this usage guide. The program will not execute if this flag is present.
695691
- `-k, --keepalive [true | false]`: Specifies whether to stop execution if there are no events to process. This defaults to `false`, meaning that the program will stop executing when there are no more events on the event queue. If you set this to `true`, then the program will keep executing until either the `timeout` logical time is reached or the program is externally killed. If you have `physical action`s, it usually makes sense to set this to `true`.
696692
- `-l, --logging [ERROR | WARN | INFO | LOG | DEBUG]`: The level of logging messages from the reactor-ts runtime to to print to the console. Messages tagged with a given type (error, warn, etc.) will print if this argument is greater than or equal to the level of the message (`ERROR` < `WARN` < `INFO` < `LOG` < `DEBUG`).
697-
- `-h, --help`: Print this usage guide. The program will not execute if this flag is present.
698-
693+
- `-o, --timeout <duration> <units>`: Stop execution when logical time has advanced by the specified _duration_. The units can be any of nsec, usec, msec, sec, minute, hour, day, week, or the plurals of those. For the duration and units of a timeout argument to be parsed correctly as a single value, these should be specified in quotes with no leading or trailing space (e.g. '5 sec').
694+
- `--single-threaded`: Specify to execute in a single thread.
695+
- `-w, --workers <n>`: Execute using `<n>` worker threads if possible. This option is incompatible with the `single-threaded` option.
699696
If provided, a command line argument will override whatever value the corresponding target property had specified in the source .lf file.
700697

701698
Command line options are parsed by the [command-line-arguments](https://github.com/75lb/command-line-args) module with [these rules](https://github.com/75lb/command-line-args/wiki/Notation-rules). For example

0 commit comments

Comments
 (0)