.. _glossary: Glossary ======== Here are some commonly used Malcolm terms. .. define references for `Attribute_` and `attribute_` that don't conflict with .. the one for `Attribute` that links to the python class .. _attribute_: Attribute --------- An `Attribute` is the interface to an object attached to a `block_` that holds a current value with alarm and timeStamp and some meta information. If writeable it can accept `Put` requests to run a remote procedure. It is a user centred view, backed by an `AttributeModel` to hold the data. Introduced in the `counter_tutorial`. .. _block_: Block ----- A `Block` is the interface to a single object with `Methods ` and `Attributes `. It is a user centred view, backed by a `BlockModel` to hold the data. Introduced in the `hello_tutorial`. .. _clientcomms_: ClientComms ----------- A `ClientComms` is a special `controller_` that provides access to remote `Blocks ` hosted by another Malcolm `process_` with a `servercomms_`. Introduced in the `hello_tutorial`. .. _context_: Context ------- A `Context` is a utility object that can make a `block_` View for any `controller_` in the current Malcolm `process_`. It is also used by these Views for calling Methods and Putting to Attributes in a synchronous and asynchronous fashion, and managing the returns from these requests in an ordered fashion. Introduced breifly in the `hello_tutorial`, then in more depth in the `motion_tutorial`. .. _controller_: Controller ---------- A `Controller` is responsible for making a `block_` View on request, possibly synchronizing its state with some hardware. Introduced in the `hello_tutorial`. .. _design_: Design ------ A `JSON`_ file that describes the settings of a Block in the `device_layer_` or the `scan_layer_`. It is generated by storing the values of all config tagged Attributes of each child Block. Introduced in the `motion_tutorial`. .. _device_layer_: Device Layer ------------ Middle level of `block_`, corresponding to a simple device like a Motion Controller, exposing a few `Methods `, or more complex device like a Detector, exposing a configure/run interface. They manage a number of Blocks in the `hardware_layer_`. Introduced in the `motion_tutorial` and expanded on in the `detector_tutorial`. .. _exports_: Exports ------- An `attribute_` of a `ManagerController`, this allows promoting of child `Attributes ` and `Methods ` to the parent. It can be used to define an interface for a top level part like the `PandAPcompPart` to use, while allowing flexibility of the exact layout of the `block_` design. Introduced in the `panda_tutorial`. .. _future_: Future ------ A `Future` represents the result of an asynchronous computation. It is typically returned by a `context_` or a `block_` View when using one of its ``_async`` methods to call a `method_` or Put to an `attribute_` without waiting for it to complete. Introduced in the `scanning_tutorial`. .. _hardware_layer_: Hardware Layer -------------- Contains the lowest level of `block_`, providing an interface that directly exposes the `Attributes ` that the hardware provides. Introduced in the `motion_tutorial`. .. _hook_: Hook ---- A `Hook` is an object created by a `controller_` that `Parts ` can register with so that arbitrary logic is run concurrently during specific times in Controller `Methods `. Introduced in the `detector_tutorial`. .. _include_: Include ------- A YAML_ file containing a number of `part_` and child `block_` definitions that can be used in the creation of a new Block. Typically used when there is a repeated pattern of components that are used in the construction of many different Block types. Introduced in the `areadetector_tutorial`. .. _info_: Info ---- An `Info` is an object created by a `part_` that is passed up to its parent `controller_` in response to a `hook_` or asynchronously by the call of `PartRegistrar.report()`. These may they be passed back down to all the children of the Controller via another Hook. Introduced in the `detector_tutorial`. .. _initial_design_: Initial Design -------------- This is the `design_` that will be loaded to a `block_` in the `device_layer_` or `scan_layer_` when Malcolm starts up. Introduced in the `areadetector_tutorial`. .. _method_: Method ------ A `Method` is the interface to an object attached to a `block_` that holds meta information about what arguments it takes and receives, and can accept `Post` requests to run a remote procedure. It is a user centred view, backed by a `MethodModel` to hold the data. Introduced in the `hello_tutorial`. .. _mri_: mri --- Malcolm Resource Identifier. A unique name for a `controller_` within a `process_` that becomes the way clients ask for a particular `block_`. Introduced in the `hello_tutorial`. .. _part_: Part ---- A `Part` is attached to a `controller_`, and is also able to contribute `Methods ` and `Attributes ` to the Controller's `block_`. It can also register to be run at specific times during Controller Methods to contribute logic. Introduced in the `hello_tutorial`. .. _process_: Process ------- A Malcolm `Process` hosts a number of `controller_` instances that can handle requests meant for a particular `block_`. Introduced in the `hello_tutorial`. .. _process_definition_: Process Definition ------------------ The top level YAML file which defines the Blocks that will be hosted by a single Malcolm Process. This will only instantiate blocks defined in other YAML files and optionally provide one or more defines. This file may not contain controllers or parts. A process definition file is passed to imalcolm.py at startup via a command line parameter. Introduced in the `hello_tutorial`. .. _scan_layer_: Scan Layer ---------- Top level of `block_`, corresponding to a combination of Devices making up a scan. Introduced in the `scanning_tutorial`. .. _servercomms_: ServerComms ----------- A `ServerComms` is a special `controller_` that provides access to the `Blocks ` hosted by the current Malcolm `process_`. Introduced in the `hello_tutorial`. .. _tags_: Tags ---- Freeform text strings that can be used to pass particular information about an `attribute_` or `method_` to users of a `block_` like the GUI widget, or whether the Attribute should be loaded/saved by a parent block. The meaning of individual tags is outlined in the `supported_tags` page. Introduced in the `counter_tutorial`. .. _template_design_: Template Design --------------- A read-only `design_` that is provide by Malcolm itself. It always starts with the string ``template_``. It can either be a sensible set of defaults for a particular Block that can be used as is (like ``template_hardware_gate`` for a detector) or act as a starting point for a user design (like ``template_pcomp`` for a PandA). Introduced in the `areadetector_tutorial`.