POLARIS COR Documentation

Michael Hope

Memory Engine

Allocate_Singleton_N <TYPE> (arg_1, arg_2, …, arg_N)– Allocate a single POLARIS object of TYPE constructed with N void*

arguments

Free_Singleton <TYPE> (object)– Free the specified single POLARIS object of TYPE

Execution Engine

Conditional– Any static function which takes a void* input and returns a boolean

Schedulable– Any static function which takes a void* input and returns void

void Load_Register (Conditional, Schedulable)– Execution Object will begin executing Conditional every iteration– If Conditional succeeds, Execution Object will execute Schedulable

void Unload_Register ()– Execution Object will do nothing every iteration

COR Meta StructuresOverview

A POLARIS component is specified using Meta Structures defined in the COR

Each POLARIS component is divided into 3 parts:

– Functionalities: declare the concepts of interest to the specified component and define functions which use these concepts

– Translations: define pre-access logistics for the specified concepts

– Base: place data members and defines the physical access of data members

4

COR Meta StructuresFunctionalities - Overview

Functionality classes declare the concepts of interest to the specified component

There are 4 main types of concepts that can be specified:

– Readable Concepts: these are type-name pairs which the specified component is interested in reading from

– Writeable Concepts: these are type-name pairs which the specified component is interested in being able to write to

– Callable Concepts: these are function signatures which the specified component is interested in being able to call

– Schedulable Concepts: these are special functions which the specified component is interested in scheduling to run at some future iteration

COR Meta StructuresFunctionalities - Anatomy

FUNCTIONALITIES ROOT_FUNCTIONALITIES (MyComponent){

READ_CONCEPT (int, id);

WRITE_CONCEPT (float, length);

READ_WRITE_CONCEPT (vector<int>, path);

CALL_CONCEPT_1 (int, Choose_Destination, float, location)

SCHEDULABLE_CONCEPT (Compute_Route, MyComponent)…Other Concepts…

};

COR Meta StructuresFunctionalities - Declarations

FUNCTIONALITIES – Declarator for a functionalities class

ROOT_FUNCTIONALITIES (COMPONENT_NAME) {…FunctionalitiesBody…};– Declare a non-inheriting functionalities class for the named component

DERIVED_FUNCTIONALITIES_N (COMPONENT_NAME, PARENT_1, PARENT_2, …, PARENT_N) {…FunctionalitiesBody…};– Declare a functionalities class which inherits from specified parents for

the named component

COR Meta StructuresFunctionalities – Concept Declaration Syntax

READ_CONCEPT (DATA_TYPE, CONCEPT_NAME)– Declare a type-name pair for a concept the component is interested in being able to read from

WRITE_CONCEPT (DATA_TYPE, CONCEPT_NAME)– Declare a type-name pair for a concept the component is interested in being able to write to

READ_WRITE_CONCEPT (DATA_TYPE, CONCEPT_NAME)– Declare a type-name pair for a concept the component is interested in being able to read or write to

CALL_CONCEPT_N (RETURN_TYPE, CONCEPT_NAME, PARAM_TYPE_1, PARAM_NAME_1, …, PARAM_TYPE_N, PARAM_NAME_N)– Declare a function signature of the specified name the component is interested in being able to call

with input parameters of the specified types and names

SCHEDULABLE_CONCEPT (COMPONENT_NAME, CONCEPT_NAME)– Declare a schedulable concept of the specified name which the component (indicated by

COMPONENT_NAME) is intersted in being able to schedule

COR Meta StructuresFunctionalities – Concept Definition Syntax

DEFINE_CALL_CONCEPT_N (COMPONENT_NAME, RETURN_TYPE, CONCEPT_NAME, PARAM_TYPE_1, PARAM_NAME_1, …, PARAM_TYPE_N, PARAM_NAME_N) {…FunctionBody…};– Supply the function body for the specified callable concept– Member functionalities accessible via: this->

DEFINE_SCHEDULABLE_CONCEPT (COMPONENT_NAME, CONCEPT_NAME) {…FunctionBody…};– Supply the function body for the specified schedulable concept– Member functionalities accessible via : pthis->

pthis– A pointer parameter passed implicitly to every schedulable which provides accessibility

to the functionalities of the component

9

COR Meta StructuresFunctionalities – Using Concepts

There are 3 primary formats to use concepts in functions

Basic Form: used in most cases– Requires only the type of the calling component to be passed

Standard Form: used when it is necessary to clarify the communication type– Requires an additional Translation_Code to be passed– In the Basic Form, the Translation_Code is implicitly defined as Send_Local_Query

Full Form: used when specifying which version of the concept is desired– Requires an additional Target_Type to be passed– In all other forms, Target_Type may be specified as NULLCLASS

GET_TYPE(CONCEPT_NAME)– Retrieve the type of the specified concept

T– A type implicit in all POLARIS classes, it holds the type of the calling component’s “this”

COR Meta StructuresFunctionalities – Using Concepts

Readable Concepts– Full: [Concept Value] CONCEPT_NAME <This_Type, Translation_Code, Target_Type> ()– Standard: [Concept Value] CONCEPT_NAME <This_Type, Translation_Code> ()– Basic: [Concept Value] CONCEPT_NAME <This_Type> ()

Writeable Concepts– Full: CONCEPT_NAME <This_Type, Translation_Code, Target_Type> (Set Value)– Standard: CONCEPT_NAME <This_Type, Translation_Code> (Set Value)– Basic: CONCEPT_NAME <This_Type> (Set Value)

Call_N Concepts– Full: [Return] CONCEPT_NAME <This_Type, Translation_Code, Target_Type> (…Call Parameters…)– Standard: [Return] CONCEPT_NAME <This_Type, Translation_Code> (… Call Parameters …)– Basic: [Return] CONCEPT_NAME <This_Type> (… Call Parameters …)

Schedulable Concepts– Full: bool CONCEPT_NAME <This_Type, Translation_Code, Target_Type> (Conditional)– Standard: bool CONCEPT_NAME <This_Type, Translation_Code> (Conditional)– Basic: bool CONCEPT_NAME <This_Type> (Conditional)

11

COR Meta StructuresTranslations - Overview

Translation classes declare the access logistics for concepts related to the specified component

There are several primary reasons to define Translations:

– Conversion: convert the concept to a different format

– Re-naming: re-name the concept

– Search: develop a chain of responsibility used to locate the concept with little knowledge of the data’s location

– Protection: authorize access by request type or utilize a safe method to access the concept

12

COR Meta StructuresTranslations - Anatomy

TRANSLATIONS ROOT_TRANSLATIONS (MyComponent){

DECLARE_READ_TRANSLATIONS (int, id);//Note: Every concept must declare its’ translations once before definion

BASIC_PARENT_READ_QUERY (int, id);

BASIC_AUTHORIZE_INTERNAL_READ_AS_LOCAL (int, id);

DECLARE_CALL_0_TRANSLATIONS (int, Choose_Destination, float, location);

BASIC_LOCAL_CALL_0_ACCESS (int, Choose_Destination, float, location);

…Other Translations…

};

COR Meta StructuresTranslations – Translation Codes

Translation Codes are customizable tags which are intended to be used by developers to communicate qualitatively among themselves

Basic Incoming Codes:– Incoming_External_Query: An external entity is making the query– Incoming_Internal_Query: Another component within the entity is making the query– Incoming_Local_Query: The component itself is making the query– Incoming_Access_Query: Call an access function

Basic Outgoing Codes:– Send_External_Query: Identify self as external to the target entity– Send_Internal_Query: Identify self as another component within the target entity– Send_Local_Query: Identify self as the component itself– Send_Access_Query: Call an access function

14

COR Meta StructuresTranslations - Declarations

TRANSLATIONS– Declarator for a translations class

ROOT_TRANSLATIONS(COMPONENT_NAME) {…TranslationsBody…};– Declare a non-inheriting translations class for the named component

DERIVED_TRANSLATIONS_N (COMPONENT_NAME, PARENT_1, PARENT_2, …, PARENT_N) {…TranslationsBody…};– Declare a translations class which inherits from specified parents for

the named component

15

COR Meta StructuresTranslations – Translation Declaration Syntax DECLARE_READ_TRANSLATION (DATA_TYPE, CONCEPT_NAME)

– Declare a type-name pair for a concept the component is interested in being able to read from

DECLARE_WRITE_TRANSLATION (DATA_TYPE, CONCEPT_NAME)– Declare a type-name pair for a concept the component is interested in being able to write to

DECLARE_READ_WRITE_TRANSLATIONS (DATA_TYPE, CONCEPT_NAME)– Declare a type-name pair for a concept the component is interested in being able to read or write to

DECLARE_CALL_CONCEPT_N_TRANSLATIONS (RETURN_TYPE, CONCEPT_NAME, PARAM_TYPE_1, PARAM_NAME_1, …, PARAM_TYPE_N, PARAM_NAME_N)– Declare a function signature of the specified name the component is interested in being able to call

with input parameters of the specified types and names

DECLARE_SCHEDULABLE_TRANSLATIONS (COMPONENT_NAME, CONCEPT_NAME)– Declare a schedulable concept of the specified name which the component (indicated by

COMPONENT_NAME) is intersted in being able to schedule

16

COR Meta StructuresTranslations – Basic Translations

Note: [*] is READ, WRITE, READ_WRITE, CALL_N, or SCHEDULABLE

BASIC_[*]_ACCESS (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters))– Translate any Incoming_Access_Queries for the concept directly to the access function

BASIC_LOCAL_[*]_ACCESS (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters))– Translate any Incoming_Local_Queries for the concept directly to the access function

BASIC_CHILD_[*]_QUERY (DATA_TYPE, CONCEPT_NAME, CHILD_NAME, …(CALL_N paramaters))– Translate any Incoming_Local_Queries about the concept into a Send_Internal_Query of the specified child

component

BASIC_PARENT_[*]_QUERY (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters))– Translate any Incoming_Local_Queries about the concept into a Send_Internal_Query of the parent component

BASIC_AUTHORIZE_X_[*]_AS_Y (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters))– Translate any X queries as Y queries– i.e. BASIC_AUTHORIZE_EXTERNAL_AS_INTERNAL translates any Incoming_External_Queries as

Incoming_Local_Queries

17

COR Meta StructuresTranslations – Advanced Translations

Standardized Polymorphic and Advanced Communication Translations

18

COR Meta StructuresTranslations – Custom Translations

Note: [*] is READ, WRITE, READ_WRITE, CALL_N, SCHEDULABLE, or [BLANK]

Custom Translations may be defined to get more advanced behavior over the Basic and Advanced Translations. Note that IDE support is not available when defining custom translations.

DEFINE_[*]_TRANSLATION (TARGET_TYPE, TRANSLATION_CODE, DATA_TYPE, CONCEPT_NAME, …(CALL_N parameters)) {…TranslationFunctionBody…}– Define a custom translation– Includes use of an optional TARGET_TYPE parameter; this allows the user to specify

additional type information, most commonly the version of the concept of interest

PTHIS– A macro which resolves the “this” pointer so it behaves as the true current type

19

COR Meta StructuresBase - Overview

Base classes place data members, defines the physical access of data members, and specifies external type information

There are 5 primary definitions included in Base classes

– Execution Behavior: determining whether the component is an execution object (can run schedulables) or a data object (cannot run schedulables)

– Binding Concepts: signifying the “physical” form of concepts

– Connecting Components: defining and establishing connections with child and external components

– Access Functions: the terminal translation function which “physically” touches the data

– Type Resolution: develop a chain of responsibility to determine non-local types

20

COR Meta StructuresBase - Anatomy

COMPONENT ROOT_EXECUTION_COMPONENT (MyComponent){

BASIC_READ_ACCESSOR (int, id);

BIND_DATA_CONCEPT (int, id);

REGISTER_TYPE (id, my_id);

GET_TYPE_FROM_COMPONENT (OtherComponent, location);

BIND_EXTERNAL_COMPONENT (OtherComponent, node);

…Other Base Definitions…

};

COR Meta StructuresBase – Declarations + Execution Behavior

Declares whether the component is an execution object (can run schedulables) or a data object (cannot run schedulables)

COMPONENT– Declarator for a component base class

ROOT_EXECUTION_COMPONENT(COMPONENT_NAME) {…BaseBody…};– Declare a non-inheriting base class for the named component which can run schedulables

DERIVED_EXECUTION_COMPONENT (COMPONENT_NAME, PARENT) {… BaseBody …};– Declare a base class which inherits from the specified parent for the named component which can run schedulables– Multiple inheritance is not available for base classes

ROOT_DATA_COMPONENT(COMPONENT_NAME) {… BaseBody …};– Declare a non-inheriting base class for the named component which cannot run schedulables

DERIVED_DATA_COMPONENT (COMPONENT_NAME, PARENT) {… BaseBody …};– Declare a base class which inherits from the specified parent for the named component which cannot run

schedulables– Multiple inheritance is not available for base classes

22

COR Meta StructuresBase – Binding Concepts + Connecting Components Binding concepts involves signifying the “physical” form of concepts and

establishing their types. Connecting components involves defining and establishing ties with child and external components

BIND_DATA_CONCEPT (DATA_TYPE, CONCEPT_NAME)– Places a data member of DATA_TYPE locally in the component and registers its’ type as

CONCEPT_NAME_type

BIND_CHILD_COMPONENT (CHILD_TYPE, CHILD_NAME)– Places a pointer to a child component of CHILD_TYPE locally in the component and

registers its’ type as CHILD_NAME_type

BIND_EXTERNAL_COMPONENT (EXTERNAL_TYPE, EXTERNAL_NAME)– Places a pointer to an external component of EXTERNAL_TYPE locally in the component

and registers its’ type as EXTERNAL_NAME_type

23

COR Meta StructuresBase – Access Functions

Note: [*] is READ, WRITE, READ_WRITE, CALL_N, or SCHEDULABLE

Access functions are the terminal translation function which “physically” touches the data

BASIC_[*]_ACCESSOR (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters))– Read/Write/Call/Schedule a local variable/function called CONCEPT_NAME

DEFINE_[*]_ACCESSOR (DATA_TYPE, CONCEPT_NAME, …(CALL_N paramaters)) {…FunctionBody…};– Define a custom function body for an accessor to CONCEPT_NAME

24

COR Meta StructuresBase – Type Resolution

Type resolution develops a chain of responsibility to determine non-local types

REGISTER_TYPE (DATA_TYPE, CONCEPT_NAME)– Establishes a definition called CONCEPT_NAME_type of the chosen DATA_TYPE

REGISTER_ALIAS (CONCEPT_NAME, CONCEPT_NAME_ALIAS)– Establishes an alias for the specified concept

GET_TYPE_FROM_PARENT (CONCEPT_NAME)– Query the parent about the type for the specified concept

GET_TYPE_FROM_LOCAL_COMPONENT (COMPONENT_NAME, CONCEPT_NAME)– Query the specified local (child or external) component about the type for the specified concept

GET_TYPE_FROM_COMPONENT (COMPONENT_NAME, CONCEPT_NAME)– Query the specified global component about the type for the specified concept

25