support variable buffer sizes in allocator

Closes #713

doc/User-Guide.adoc

@@ -0,0 +1,32 @@
+= User Guide
+:toc:
+:numbered:
+
+== Integration files
+
+For each RecordFlux specification file with the `.rflx` file extension, users
+may provide a file with the same name but the `.rfi` file extension. This is
+useful to specify buffer sizes for sessions. This file is in the YAML data
+format. Buffer sizes are provided in bytes. If no such file is provided,
+RecordFlux uses a default buffer size of 4096 bytes.
+
+*Integration file structure*
+
+The following example of an integration file defines, for the session
+`My_Session`, a default buffer size of 4096 bytes, a buffer size of 2048 bytes
+for the global variable `My_Global_Var`, and a buffer size of 1024 bytes for
+the variable `My_State_Variable` defined in the state `My_State`.
+
+[source,yaml]
+----
+Session:
+  My_Session:
+    Buffer_Size:
+      Default: 4096
+      Global:
+        My_Global_Var: 2048
+      Local:
+        My_State:
+          My_State_Variable: 1024
+----
+

rflx/cli.py

@@ -6,7 +6,7 @@
 from collections import defaultdict
 from multiprocessing import cpu_count
 from pathlib import Path
-from typing import Dict, List, Sequence, Union
+from typing import Dict, List, Sequence, Tuple, Union
 
 import librflxlang
 from pkg_resources import get_distribution
@@ -16,6 +16,7 @@
 from rflx.generator import Generator
 from rflx.graph import Graph
 from rflx.identifier import ID
+from rflx.integration import Integration
 from rflx.model import Message, Model, Session
 from rflx.pyrflx import PyRFLXError
 from rflx.specification import Parser
@@ -248,10 +249,11 @@ def generate(args: argparse.Namespace) -> None:
     if not args.output_directory.is_dir():
         fail(f'directory not found: "{args.output_directory}"', Subsystem.CLI)
 
-    model = parse(args.files, args.no_verification, args.workers)
+    model, integration = parse(args.files, args.no_verification, args.workers)
 
     generator = Generator(
         model,
+        integration,
         args.prefix,
         reproducible=os.environ.get("RFLX_REPRODUCIBLE") is not None,
         debug=args.debug,
@@ -264,7 +266,9 @@ def generate(args: argparse.Namespace) -> None:
         generator.write_top_level_package(args.output_directory)
 
 
-def parse(files: Sequence[Path], skip_verification: bool = False, workers: int = 1) -> Model:
+def parse(
+    files: Sequence[Path], skip_verification: bool = False, workers: int = 1
+) -> Tuple[Model, Integration]:
     parser = Parser(skip_verification, cached=True, workers=workers)
     error = RecordFluxError()
     present_files = []
@@ -287,14 +291,14 @@ def parse(files: Sequence[Path], skip_verification: bool = False, workers: int =
         error.extend(e)
 
     error.propagate()
-    return model
+    return model, parser.get_integration()
 
 
 def graph(args: argparse.Namespace) -> None:
     if not args.output_directory.is_dir():
         fail(f'directory not found: "{args.output_directory}"', Subsystem.CLI)
 
-    model = parse(args.files, args.no_verification)
+    model, _ = parse(args.files, args.no_verification)
     locations: Dict[str, Dict[str, Dict[str, Dict[str, int]]]] = defaultdict(dict)
 
     for m in [*model.messages, *model.sessions]: