diff --git a/doc/devel/draw/AdviceBindingIndex-1.svg b/doc/devel/draw/AdviceBindingIndex-1.svg new file mode 100644 index 000000000..ea7a5aaa0 --- /dev/null +++ b/doc/devel/draw/AdviceBindingIndex-1.svg @@ -0,0 +1,1000 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + Advice Binding Index Structures + + + Ichthyostega + + + design sketch: Advice binding match implementation + 2010 + + + + + + + + + + + + + + + Provisions + + + + + + Requests + Match + + AdviceProvision + + + + hash + + + + + + + hash + + + + + + + + + + AdviceProvision + + + + AdviceRequest + + + + AdviceRequest + + + + AdviceRequest + + + + AdviceRequest + + + + + + + + + + + + + + + Advice Solution + diff --git a/doc/devel/uml/class163973.html b/doc/devel/uml/class163973.html new file mode 100644 index 000000000..4a627eca4 --- /dev/null +++ b/doc/devel/uml/class163973.html @@ -0,0 +1,21 @@ + + + + + + +Class Advice + + + + + +
Class Advice
+

+ + + + +

Declaration :

Stereotype: entity

+ + diff --git a/doc/devel/uml/class164101.html b/doc/devel/uml/class164101.html new file mode 100644 index 000000000..0c7acab23 --- /dev/null +++ b/doc/devel/uml/class164101.html @@ -0,0 +1,21 @@ + + + + + + +Class PointOfAdvice + + + + + +
Class PointOfAdvice
+

+ + + + +

Declaration :

Directly inherited by : ActiveProvision AdviceLink

+ + diff --git a/doc/devel/uml/class164229.html b/doc/devel/uml/class164229.html new file mode 100644 index 000000000..8272e8df6 --- /dev/null +++ b/doc/devel/uml/class164229.html @@ -0,0 +1,25 @@ + + + + + + +Class Advisor + + + + + +
Class Advisor
+

+ + + + +

Declaration :

Stereotype: actor

+
+ +
Relation <unidirectional association>

Declaration :

Stereotype: add

+
+ + diff --git a/doc/devel/uml/class164357.html b/doc/devel/uml/class164357.html new file mode 100644 index 000000000..d81837c75 --- /dev/null +++ b/doc/devel/uml/class164357.html @@ -0,0 +1,25 @@ + + + + + + +Class Advised + + + + + +
Class Advised
+

+ + + + +

Declaration :

Stereotype: actor

+
+ +
Relation <unidirectional association>

Declaration :

Stereotype: owns

+
+ + diff --git a/doc/devel/uml/class164485.html b/doc/devel/uml/class164485.html new file mode 100644 index 000000000..877b85817 --- /dev/null +++ b/doc/devel/uml/class164485.html @@ -0,0 +1,25 @@ + + + + + + +Class Request + + + + + +
Class Request
+

+ + + + +

Declaration :

+ +
Relation <association>

Declaration :

+
Operation getAdvice

Declaration :

+

All public operations : getAdvice

+ + diff --git a/doc/devel/uml/class164613.html b/doc/devel/uml/class164613.html new file mode 100644 index 000000000..d65a66606 --- /dev/null +++ b/doc/devel/uml/class164613.html @@ -0,0 +1,25 @@ + + + + + + +Class Provision + + + + + +
Class Provision
+

+ + + + +

Declaration :

+ +
Relation <association>

Declaration :

+
Operation setAdvice

Declaration :

+

All public operations : setAdvice

+ + diff --git a/doc/devel/uml/class164741.html b/doc/devel/uml/class164741.html new file mode 100644 index 000000000..ff2e4bdb7 --- /dev/null +++ b/doc/devel/uml/class164741.html @@ -0,0 +1,24 @@ + + + + + + +Class Binding + + + + + +
Class Binding
+

+ + + + +

Declaration :

+ +
Relation <association>

Declaration :

+
Relation <association>

Declaration :

+ + diff --git a/doc/devel/uml/class165893.html b/doc/devel/uml/class165893.html new file mode 100644 index 000000000..273315c31 --- /dev/null +++ b/doc/devel/uml/class165893.html @@ -0,0 +1,25 @@ + + + + + + +Class AdviceLink + + + + + +
Class AdviceLink
+

+ + + + +

Declaration :

Directly inherited by : Provision Request

+
+ +
Relation <unidirectional association>

Declaration :

Stereotype: attach

+
+ + diff --git a/doc/devel/uml/class166021.html b/doc/devel/uml/class166021.html new file mode 100644 index 000000000..76eeedbec --- /dev/null +++ b/doc/devel/uml/class166021.html @@ -0,0 +1,24 @@ + + + + + + +Class ActiveProvision + + + + + +
Class ActiveProvision
+

+ + + + +

Declaration :

+ +
Relation <unidirectional association>

Declaration :

Stereotype: holds

+
+ + diff --git a/doc/devel/uml/class166149.html b/doc/devel/uml/class166149.html new file mode 100644 index 000000000..c28e6bf8f --- /dev/null +++ b/doc/devel/uml/class166149.html @@ -0,0 +1,23 @@ + + + + + + +Class AdviceSystem + + + + + +
Class AdviceSystem
+

+ + + + +

Declaration :

+ +
Relation <unidirectional association>

Declaration :

+ + diff --git a/doc/devel/uml/class166277.html b/doc/devel/uml/class166277.html new file mode 100644 index 000000000..34565c66b --- /dev/null +++ b/doc/devel/uml/class166277.html @@ -0,0 +1,23 @@ + + + + + + +Class Index + + + + + +
Class Index
+

+ + + + +

Declaration :

+ +
Relation <directional composition>

Declaration :

+ + diff --git a/doc/devel/uml/classdiagrams.html b/doc/devel/uml/classdiagrams.html index ed532bb62..d3ac050c6 100644 --- a/doc/devel/uml/classdiagrams.html +++ b/doc/devel/uml/classdiagrams.html @@ -16,6 +16,7 @@ + diff --git a/doc/devel/uml/classes.html b/doc/devel/uml/classes.html index ed22c27b6..48eed5347 100644 --- a/doc/devel/uml/classes.html +++ b/doc/devel/uml/classes.html @@ -17,6 +17,12 @@
Advice entities
Asset Kinds
Automation Entities
Builder Entities
+ + + + + + @@ -28,6 +34,7 @@ + @@ -91,6 +98,7 @@ + @@ -132,6 +140,7 @@ + @@ -142,6 +151,7 @@ + @@ -160,6 +170,7 @@ + diff --git a/doc/devel/uml/classes_list.html b/doc/devel/uml/classes_list.html index 916725182..4551eea74 100644 --- a/doc/devel/uml/classes_list.html +++ b/doc/devel/uml/classes_list.html @@ -18,6 +18,12 @@
AbstractMO
ActiveProvision
Adviceentity
AdviceLink
AdviceSystem
Advisedactor
Advisoractor
AFrame
Allocationa directive to place a MObject in a specific way
AppconfigsingletonSingleton to hold inevitable global flags and constants and for performing erarly (static) global initialization tasks.
AutoAutomation data for some parameter (i.e. a time varying function)
BackendCache
BareEntryID
Binding
Binding
BuffHandle
BuffTable
HandlingPatterninterface
Id
ImplFacade
Index
InstanceHandle
InterpolatorProvides the implementation for getting the acutal value of a time varying or automated effect/plugin parameter
Invalid
PlayheadCursor
Plug
PluginAdapterAdapter used to integrage an effects processor in the render pipeline
PointOfAdvice
Prefetch
Previewalternative version of the media data, probably with lower resolution
Prockey abstraction: data processing asset
Project
ProjectorSpecial video processing node used to scale and translate image data.
Prototype
Provision
Proxy
PullInput
Query
RenderGraph
RenderStateEncapsulates the logic used to get a "current render process" in accordance to the currentyl applicable controller settings. The provided StateProxy serves to hold any mutalbe state used in the render process, so the rest of the render engine can be stateless.
RenderTask
Request
Resolution
ResolverBase
ResolvingFacility
- - + + @@ -41,24 +41,24 @@ - + - - - - - - - - + + + + - - + + + + + +
AbstractMO
+ActiveProvision
+Advice
+AdviceLink
+AdviceSystem
+Advised
+Advisor
AFrame
Allocation
Appconfig
@@ -29,6 +35,7 @@ Auto
BackendCache
BareEntryID
+Binding
Binding
BuffHandle
BuffTable
@@ -92,6 +99,7 @@ HandlingPattern
Id
ImplFacade
+Index
InstanceHandle
Interpolator
Invalid
@@ -133,6 +141,7 @@ PlayheadCursor
Plug
PluginAdapter
+PointOfAdvice
Prefetch
Preview
Proc
@@ -143,6 +152,7 @@ Project
Projector
Prototype
+Provision
Proxy
PullInput
Query
@@ -161,6 +171,7 @@ RenderGraph
RenderState
RenderTask
+Request
Resolution
ResolverBase
ResolvingFacility
diff --git a/doc/devel/uml/fig141445.png b/doc/devel/uml/fig141445.png new file mode 100644 index 000000000..7eab04117 Binary files /dev/null and b/doc/devel/uml/fig141445.png differ diff --git a/doc/devel/uml/fig141573.png b/doc/devel/uml/fig141573.png new file mode 100644 index 000000000..986ef241d Binary files /dev/null and b/doc/devel/uml/fig141573.png differ diff --git a/doc/devel/uml/index.html b/doc/devel/uml/index.html index 490baddde..2a066763e 100644 --- a/doc/devel/uml/index.html +++ b/doc/devel/uml/index.html @@ -147,7 +147,7 @@ Documentation
Artifact Lumiera

the main executable to be built

Depends on common

Depends on gui

Depends on proc

Depends on backend

Stereotype: executable

-

executable associated with : arender, renderstate, label, nodecreatertool, projector, interpolator, paramprovider, mask, mobject, source, frame, effect, buildertool, segmentationtool, link, parameter, renderengine, glbuf, procnode, stateproxy, edl, fixture, glpipe, main, conmanager, clip, vrender, placement, sessionimpl, builderfacade, aframe, assembler, trafo, allocation, vframe, toolfactory, hub, buildable, abstractmo, exitnode, pathmanager, track, meta, fixedlocation, relativelocation, controllerfacade, rendergraph, pluginadapter, explicitplacement, auto, glrender

+

executable associated with : explicitplacement, auto, glrender, arender, renderstate, label, nodecreatertool, projector, interpolator, paramprovider, mask, mobject, source, frame, effect, buildertool, segmentationtool, link, parameter, renderengine, glbuf, procnode, stateproxy, edl, fixture, glpipe, main, conmanager, clip, vrender, placement, sessionimpl, builderfacade, aframe, assembler, trafo, allocation, vframe, toolfactory, hub, buildable, abstractmo, exitnode, pathmanager, track, meta, fixedlocation, relativelocation, controllerfacade, rendergraph, pluginadapter

Artifact main

Stereotype: source

@@ -1502,8 +1502,42 @@ undo
Class C_Instance
Class InstanceHandle
+ +

5.2 Class View Advice

+
+ +

+

Advice entities



+
Class Advice
+
Class PointOfAdvice
+
Class Advisor
+
Class Advised
+
Class AdviceLink
+
Class Request
+
Class Provision
+
Class ActiveProvision
+
Class Binding
+
Class AdviceSystem
+
Class Index
+ +

+

Advice solving



+ +
Class instance

type :Provision

+
Class instance

type :Provision

+
Class instance

type :Provision

+
Class instance

type :Advisor

+
Class instance

type :Advised

+
Class instance

type :Request

+
Class instance

type :Advised

+
Class instance

type :Request

+
Class instance

type :Binding

+
Class instance

type :Binding

+
Class instance

type :Binding

+
Class instance

type :Binding

+
Class instance

type :Binding

-

5.2 Class View StreamType

+

5.3 Class View StreamType

@@ -1515,10 +1549,10 @@ undo
Class MediaKind
-

5.3 Package ConfigQuery

+

5.4 Package ConfigQuery

-

5.3.1 Component View Query System overview

+

5.4.1 Component View Query System overview

@@ -1534,7 +1568,7 @@ undo
Component DefaultsManager
-

5.3.2 Class View query

+

5.4.2 Class View query

@@ -1559,27 +1593,27 @@ undo
Class ResultSet
-

5.3.3 Use Case View query use

+

5.4.3 Use Case View query use

when to query



-

5.3.3.1 Use Case create specific object

+

5.4.3.1 Use Case create specific object

-

5.3.3.2 Use Case use "default" object

+

5.4.3.2 Use Case use "default" object

-

5.3.3.3 Use Case load object from session

+

5.4.3.3 Use Case load object from session

-

5.3.3.4 Use Case add new object to session

+

5.4.3.4 Use Case add new object to session

Class User
Class Serializer
-

5.3.3.5 Use Case ConfigQuery

+

5.4.3.5 Use Case ConfigQuery

-

5.3.3.6 Use Case need sub object

+

5.4.3.6 Use Case need sub object

"default" object



@@ -1587,17 +1621,17 @@ undo
Class instance predicate impl

type :TypeHandler

-

5.4 Package Containers

+

5.5 Package Containers

-

5.4.1 Class View Custom holders

+

5.5.1 Class View Custom holders

Class Handle
Class P
-

5.5 Class View error

+

5.6 Class View error

@@ -1611,7 +1645,7 @@ undo
Class std::exception
-

5.6 Class View Service Components

+

5.7 Class View Service Components

Class Applicable
Class Tool
@@ -1621,7 +1655,7 @@ undo
Class Appconfig
-

5.7 Class View Posix Threads Abstraction

+

5.8 Class View Posix Threads Abstraction

C++ wrapers for pthreads

Class Thread
@@ -1629,7 +1663,7 @@ undo
Class Mutex
-

5.8 Class View SmartPointers

+

5.9 Class View SmartPointers

Class SmartPointer
Class shared_ptr
diff --git a/doc/devel/uml/index_60.html b/doc/devel/uml/index_60.html index c84f0a7d2..ed93942a9 100644 --- a/doc/devel/uml/index_60.html +++ b/doc/devel/uml/index_60.html @@ -28,10 +28,10 @@
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<flow>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
<transition>transition
diff --git a/doc/devel/uml/index_65.html b/doc/devel/uml/index_65.html index 77e461db5..d7919f28c 100644 --- a/doc/devel/uml/index_65.html +++ b/doc/devel/uml/index_65.html @@ -21,12 +21,21 @@ AbstractMOclass access Channeluse case access Fileuse case +ActiveProvisionclass activity finalactivity final activity finalactivity final ad1class instance ad2class instance ad3class instance add new object to sessionuse case +Adviceclass +Adviceclass view +Advice entitiesclass diagram +Advice solvingobject diagram +AdviceLinkclass +AdviceSystemclass +Advisedclass +Advisorclass AFrameclass aframeartifacta buffer and render process holding a Audio frame allocateBufferoperation @@ -60,9 +69,9 @@ aud_Aclass instance aud_aclass instance audioclass instance +audio1class instance audio1class instance audio1class instance -audio1class instance autoartifactMedia Object holding automation data AutoclassAutomation data for some parameter (i.e. a time varying function) Automation Entitiesclass diagram diff --git a/doc/devel/uml/index_66.html b/doc/devel/uml/index_66.html index 329844354..7ae707608 100644 --- a/doc/devel/uml/index_66.html +++ b/doc/devel/uml/index_66.html @@ -24,6 +24,7 @@ BackendCacheclass BackendLayerpackage BareEntryIDclass +Bindingclass Bindingclass BuffHandleclass BuffTableclass @@ -39,8 +40,8 @@ buildableartifactmarker interface denoting any MObject able to be treated by Tools buildEngineoperationMain Operation of the Builder: create a render engine for a given part of the timeline Buildercomponent -Builderpackage builderpackagesourcecode package

The Builder creating the Render Engine,
located within the MObject Subsystem +Builderpackage Builder Entitiesclass diagram Builder Tool (Visitor)class diagram Builder Workingsclass view diff --git a/doc/devel/uml/index_67.html b/doc/devel/uml/index_67.html index e1ddf1116..b7aadf243 100644 --- a/doc/devel/uml/index_67.html +++ b/doc/devel/uml/index_67.html @@ -35,49 +35,62 @@ checked_inrelationchecked_in objects are subject of cache aging and must be not in use checked_outrelationthis list keeps all mappings which are in use, and thus prevents them from Cache aging choice pseudo statechoice pseudo state -class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance class instanceclass instance -class instanceclass instance -class instanceclass instance class instanceclass instance class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance +class instanceclass instance class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance +class instanceclass instance class instanceclass instance -class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance -class instanceclass instance class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance +class instanceclass instance class instanceclass instance +class instanceclass instance clearoperationclear current session contents
without resetting overall session config.
Afterwards, the session will contain only one
empty EDL, while all Assets are retained.
client codecomponent clipartifacta Media Clip diff --git a/doc/devel/uml/index_68.html b/doc/devel/uml/index_68.html index 9866cde59..0af5dabf9 100644 --- a/doc/devel/uml/index_68.html +++ b/doc/devel/uml/index_68.html @@ -33,8 +33,8 @@ designpackage designpackageAll things concering the big picture.
Not a real code package, rather a container for design drafts, specifications, decisions. detect Channelsuse case -determine Render Paramsopaque activity action determine Render Paramsexpansion region +determine Render Paramsopaque activity action devnullclass instance Dispatchercomponent dispatchOpoperation diff --git a/doc/devel/uml/index_69.html b/doc/devel/uml/index_69.html index f2006f6ac..cd8b1183a 100644 --- a/doc/devel/uml/index_69.html +++ b/doc/devel/uml/index_69.html @@ -22,8 +22,8 @@ EDL Example1object diagramA simple example showing how the actual objects are placed in the Fixture (=definitive playlist). It shows a Video and Audio clip placed on two tracks EDL Example2object diagramMore complex example showing the Object graph in the EDL and how it is linked into the Fixture to yield the actual locations. In this example, an HUE Effect is applied on a part of the Clip EffectclassEffect or media processing component -effectartifactEffect or media processing component effectartifactEDL representation of a pluggable and automatable effect. +effectartifactEffect or media processing component Effectclass effective timeline (Fixture)node effectiveTimelinerelation diff --git a/doc/devel/uml/index_70.html b/doc/devel/uml/index_70.html index e177ed876..f8b0d3398 100644 --- a/doc/devel/uml/index_70.html +++ b/doc/devel/uml/index_70.html @@ -41,8 +41,8 @@ Fixtureclass Focus of Queryclass diagram fork activity nodefork activity node -fork pseudo statefork pseudo state fork pseudo statefork pseudo state +fork pseudo statefork pseudo state FrameclassFrames are just a low level lump of continous memory, most parts are opaque. Frames are memory sensitive, they will be small constant sized structures which can be efficently managed in a pool. Framenode FrameclassTODO: how to relate to Cehteh's Frame entity in the Backend?
The latter is the fundamental Frame entity, wheras this Object rather represents a buffer set containing frame date diff --git a/doc/devel/uml/index_71.html b/doc/devel/uml/index_71.html index 7a7e73ee2..a06017401 100644 --- a/doc/devel/uml/index_71.html +++ b/doc/devel/uml/index_71.html @@ -31,6 +31,7 @@ getoperationaccess the configuation value for a given key.
@return empty string for unknown keys, else the corresponding configuration value get frameactivity get_reproperation +getAdviceoperation getAssetoperationfind and return corresponging object getAutomationoperation getConnectionoperationTODO diff --git a/doc/devel/uml/index_72.html b/doc/devel/uml/index_72.html index 2d011b5a4..cfc9228eb 100644 --- a/doc/devel/uml/index_72.html +++ b/doc/devel/uml/index_72.html @@ -25,8 +25,8 @@ Hierarchyclass diagramLumiera Exception hierarchy howtoProcoperation@return descriptor how to build a render pipeline corresponding to this media hubartifactspecial ProcNode used to build data distributing connections -HUEclass instance HUEclass instance +HUEclass instance diff --git a/doc/devel/uml/index_73.html b/doc/devel/uml/index_73.html index d6bd98c73..60e9bcda6 100644 --- a/doc/devel/uml/index_73.html +++ b/doc/devel/uml/index_73.html @@ -24,10 +24,11 @@ id_relation ImplFacadeclass In Memory Databaseclass diagram +Indexclass inFixtureactivity action pin -inputclass instance inputclass instance inputclass instance +inputclass instance instanceoperation InstanceHandleclass instructionsrelation diff --git a/doc/devel/uml/index_79.html b/doc/devel/uml/index_79.html index 8b2bac9de..7a6016f25 100644 --- a/doc/devel/uml/index_79.html +++ b/doc/devel/uml/index_79.html @@ -21,8 +21,8 @@ offsetattributeOffset the actual position by this (time) value relative to the anchor point. TODO: Representation? OperationBaseclass orgattributeorigin or authorship id. Can be a project abbreviation, a package id or just the authors nickname or UID. This allows for the compnent name to be more generic (e.g. "blur"). Default for all assets provided by the core Lumiera codebase is "lumi". -ouputclass instance ouputclass instance +ouputclass instance ouputclass instance outPortrelationthe Port this MObject wants to be conected to Overviewcomponent diagramThis drawing shows the top level compoents and relations diff --git a/doc/devel/uml/index_80.html b/doc/devel/uml/index_80.html index 4593a9e60..b75bcbbcc 100644 --- a/doc/devel/uml/index_80.html +++ b/doc/devel/uml/index_80.html @@ -51,6 +51,7 @@ pluginadapterartifactAdapter for integrating various Effect processors in the render pipeline pnodenode pointattributeidentifying the point where the nodes should be attached +PointOfAdviceclass pos_relation Posix Threads Abstractionclass viewC++ wrapers for pthreads predecessorsrelation @@ -80,6 +81,7 @@ projectorartifactvideo ProcNode for scaling and translating image data Prototypeclass providerrelation +Provisionclass Proxyclass pulloperation PullInputclass diff --git a/doc/devel/uml/index_82.html b/doc/devel/uml/index_82.html index 69336106c..9afaba1ca 100644 --- a/doc/devel/uml/index_82.html +++ b/doc/devel/uml/index_82.html @@ -46,6 +46,7 @@ renderstateartifactrenderengine state manager RenderTaskclass reprattributehuman readable representation of the condition characterizing this allocaton, e.g. "t >= 10" +Requestclass resetoperationreset all session config and
start with a pristine default session. Resolutionclass resolveoperationcreate an actual (explicit) placement while trying to satisfy the network of adjacent objects and placements. diff --git a/doc/devel/uml/index_83.html b/doc/devel/uml/index_83.html index 1397452cc..20dc11c66 100644 --- a/doc/devel/uml/index_83.html +++ b/doc/devel/uml/index_83.html @@ -43,8 +43,8 @@ ServiceImplclass Sessioncomponent sessionartifactInterface: the session edited by the user -sessionpackagesourcecode package

Everything concerning the EDL and Session, within the MObject Subsystem Sessionpackage +sessionpackagesourcecode package

Everything concerning the EDL and Session, within the MObject Subsystem SessionclassPrimary Interface for all editing tasks.
The session contains defaults, all the assets being edited, and a set of EDL with the individual MObjects to be manipulated and rendered. Session backboneclass diagram Session partsclass view @@ -53,6 +53,7 @@ SessionImplclassImplementation class for the Session interface sessmanagerartifactglobal session access and lifecycle SessManagerclass +setAdviceoperation setup Build Paramsopaque activity action setup StateProxyopaque activity action shared_ptrclass @@ -71,15 +72,15 @@ Statenode Stateclass staterelation -state actionstate actiontry to fetch existing definition +state actionstate action state actionstate action +state actionstate action +state actionstate actiontry to fetch existing definition state actionstate action state actionstate action state actionstate action -state actionstate action state actionstate action -state actionstate action -state actionstate action +state actionstate action StateAdapterclass StateAdapter compositionclass diagram StateProxyclass diff --git a/doc/devel/uml/index_84.html b/doc/devel/uml/index_84.html index 64ca32fb8..0df6c9aef 100644 --- a/doc/devel/uml/index_84.html +++ b/doc/devel/uml/index_84.html @@ -45,12 +45,12 @@ treatoperation treatoperationThis operation is to be overloaded for the specific MObject subclasses to be treated. treatoperation +treatoperation treatoperation treatoperation -treatoperation treatoperation -treatoperation treatoperation +treatoperation TypedIDclass TypedID::Indexclass TypedID::Linkclass diff --git a/doc/devel/uml/index_86.html b/doc/devel/uml/index_86.html index 91b807e2d..99d65bb91 100644 --- a/doc/devel/uml/index_86.html +++ b/doc/devel/uml/index_86.html @@ -22,20 +22,20 @@ vframeartifacta buffer and render process holding a Video frame vid1class instance vid_Aclass instance -vid_aclass instance -vid_Aclass instance vid_Aclass instance +vid_aclass instance vid_aclass instance +vid_Aclass instance videoclass instance -videoclass instance videoclass instance +videoclass instance videoclass instance -video1class instance -video1class instance -video1class instance video1class instance +video1class instance video1class instance +video1class instance video1class instance +video1class instance VirtualMediaclass Visitableclass visitorpackagesub-namespace for visitor library implementation diff --git a/doc/devel/uml/objectdiagrams.html b/doc/devel/uml/objectdiagrams.html index cb1f81a95..bb844651a 100644 --- a/doc/devel/uml/objectdiagrams.html +++ b/doc/devel/uml/objectdiagrams.html @@ -16,6 +16,7 @@ + diff --git a/doc/devel/uml/public_operations.html b/doc/devel/uml/public_operations.html index 649a88f03..360dc30db 100644 --- a/doc/devel/uml/public_operations.html +++ b/doc/devel/uml/public_operations.html @@ -36,6 +36,7 @@ + @@ -72,15 +73,16 @@ + - - - - + + + + diff --git a/src/lib/advice.hpp b/src/lib/advice.hpp new file mode 100644 index 000000000..dd6e749eb --- /dev/null +++ b/src/lib/advice.hpp @@ -0,0 +1,481 @@ +/* + ADVICE.hpp - generic loosely coupled interaction guided by symbolic pattern + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +/** @file advice.hpp + ** Expecting Advice and giving Advice: a cross-cutting collaboration of loosely coupled participants. + ** This header exposes the basics of the advice system and the public access points. The advice system + ** is a system wide singleton service, but clients never talk directly to this singleton; rather they + ** use advice::Provision and advice::Request as access point. + ** + ** \par Advice collaboration pattern + ** Advice collaboration is a special pattern of interaction extracted from multiple use cases within + ** Lumiera. Creating this abstraction was partially inspired by aspect oriented programming, especially + ** the idea of cross-cutting the primary dependency hierarchy. Another source of inspiration where the + ** various incarnations of properties with dynamic binding. For defining the actual binding, we rely + ** on predicate notation and matching (planned: unification) as known from rule based systems. + ** + ** Definition: Advice is an optional, mediated collaboration between entities taking on + ** the roles of advisor and advised, thereby passing a custom piece of advice data, managed by + ** the advice support system. The possibility of advice is created by both of the collaborators + ** entering the system, where the advised entity exposes a point of advice, while the advising + ** entity provides an actual advice value. + ** + ** \par Collaborators + ** - the advised entity + ** - the advisor + ** - point of advice + ** - advice system + ** - the binding + ** - the advice + ** + ** Usually, the \em advised entity opens the collaboration by requesting an advice. The \em advice itself + ** is a piece of data of a custom type, which needs to be copyable. Obviously, both the advised and the + ** advisor need to share knowledge about the meaning of this advice data. The actual advice collaboration + ** happens at a \em point-of-advice, which needs to be derived first. To this end, the advised puts up an + ** \em request by providing his \em binding, which is a pattern for matching. An entity about to give advice + ** opens possible advice \em channels by putting up an advisor binding, which similarly is a pattern. The + ** advice \em system as mediator resolves both sides, by matching (which in the most general case could be + ** an unification). This process creates an advice point \em solution -- allowing the advisor to fed the + ** piece of advice into the advice channel, causing it to be placed into the point of advice. After passing + ** a certain (implementation defined) break point, the advice leaves the influence of the advisor and gets + ** exposed to the advised entities. Especially this involves copying the advice data into a location managed + ** by the advice system. In the standard case, the advised entity accesses the advice synchronously and + ** non-blocking. Typically, the advice data type is default constructible and thus there is always a basic + ** form of advice available, thereby completely decoupling the advised entity from the timings related + ** to this collaboration. + ** + ** \par interfaces and implementation + ** Client code is assumed to interface solely through the advice::Request and advice::Provision classes, + ** which both can be instantiated and copied freely, may be used as member or mixed in as baseclass. + ** The AdviceSystem on the other hand is an implementation facility (actually a singleton) and lives + ** in the advice.cpp translation unit. The interface entities inherit protected from AdviceLink, + ** which is implemented in the same scope as the AdviceSystem and thus allowed to talk to it + ** directly. The AdviceSystem in turn uses advice::Index to keep track of the collaboration + ** partners, which, for this purpose, are handled as type-erased PointOfAdvice elements. + ** The latter class contains 4 API functions used by the index to manage solutions. + ** + ** @note as of 6/2010 this is an experimental setup and implemented just enough to work out + ** the interfaces and gain practical usage experiences. Ichthyo expects this collaboration + ** service to play a central role at various places within proc-layer. + ** @todo allow variables in binding patterns + ** @todo use the lumiera MPool instead of heap allocations + ** @todo consider to provide variations of the basic behaviour by policy classes + ** @todo the implementation is generic/defensive, and could be improved and optimised + ** + ** @see AdviceBasics_test usage example + ** @see advice.cpp implementation + ** @see advice::Index index datastructure + ** @see binding.hpp + ** + */ + + +#ifndef LIB_ADVICE_H +#define LIB_ADVICE_H + + +#include "lib/error.hpp" +#include "lib/null-value.hpp" +#include "lib/advice/binding.hpp" +#include "lib/symbol.hpp" +#include "lib/util.hpp" + +#include + + +namespace lib { +namespace advice { + + using lib::Symbol; + using util::isSameObject; + + + /** + * Basic (abstracted) view of an advice collaboration partner, + * as used internally by the AdviceSystem to manage the participants. + * Each PointOfAdvice is characterised by a binding pattern, used to + * pair up advice::Request and advice::Provision entries. Moreover, + * each PointOfAdvice can refer to an existing advice solution + * provided elsewhere in the system. The specific type of advice + * (and thus the storage requirements) are abstracted away, + * as is the distinction between Request and Provision. + * + * @see AdviceSystem + * @see AdviceIndex_test + */ + class PointOfAdvice + { + Binding::Matcher pattern_; + PointOfAdvice* resolution_; + + protected: + /** define or re-define the binding, which + * specifically labels this attachment to the advice system. + * @note issuing this on an existing connection is equivalent + * to re-connecting with the new binding. + */ + void setBindingPattern (Binding const& binding) + { + pattern_ = binding.buildMatcher(); + } + + public: + explicit + PointOfAdvice (Binding const& binding) + : pattern_(binding.buildMatcher()) + , resolution_(0) + { } + + // using default copy/assignment + + + + /* == Adapter interface for use within the Index == */ + + void + setSolution (PointOfAdvice* solution =0) + { + resolution_ = solution; + } + + const PointOfAdvice* + getSolution () const + { + return resolution_; + } + + Binding::Matcher + getMatcher () const + { + return pattern_; + } + + friend HashVal + hash_value (PointOfAdvice const& entry) + { + return hash_value (entry.pattern_); + } + }; + + + + + /** + * Advice Collaboration partner, internally connected to the AdviceSystem. + * Both advice::Request and advice::Provision are linked in this way + * to an internal index datastructure, which allows to carry out + * the actual advice exchange and collaboration. + */ + class AdviceLink + : public PointOfAdvice + { + protected: + void publishProvision (PointOfAdvice*); + void discardSolutions (); + void publishRequestBindingChange(HashVal); + + void registerRequest(); + void deregisterRequest(); + + static void* getBuffer(size_t); + static void releaseBuffer (void*, size_t); + + typedef void (DeleterFunc)(void*); + static void manageAdviceData (PointOfAdvice*, DeleterFunc*); + + public: + explicit + AdviceLink (Binding const& binding) + : PointOfAdvice(binding) + { } + + // using default copy/assignment + }; + + + + + + /** + * Access point for the advising entity (server). + * This is the interface intended for client code to set and provide + * concrete advice information of a specific type AD. Instantiating + * automatically creates a \em type-guard binding pattern, but client code + * can (and typically should) provide additional predicates to define the + * "topic" this advice belongs to. This allows advice::Request entries + * to attach to the suitable advice "channels" and get the specific + * piece of advice they're looking for. + * + * Any advice::Provision remains inactive and thus invisible, until + * \link #setAdvice setting the concrete advice data \endlink. After that, + * the provided data is \em copied into the AdviceSystem and remains available + * even after the original Provision goes out of scope. Consequently, it isn't + * possible to \em modify advice data once set. But client code may retract + * the provision or change the binding pattern. + * + * @see AdviceBasics_test usage example + */ + template + class Provision + : protected AdviceLink + { + + + /* == policy definitions == */ ////TODO: extract into policy classes + + void deregistrate() { /* NOP */ } + + + public: + explicit + Provision (Literal bindingSpec =0) + : AdviceLink (Binding(bindingSpec).addTypeGuard()) + { } + + ~Provision() + { + this->deregistrate(); + } + + Provision (Provision const& o) + : AdviceLink(o) + { + setSolution ( NULL ); + } + + Provision& + operator= (Provision const& o) + { + if (!isSameObject(*this, o)) + { + AdviceLink::operator= (o); + setSolution ( NULL ); + } + } + + + void setAdvice (AD const& pieceOfAdvice) + { + publishProvision( + storeCopy (pieceOfAdvice)); + } + + void retractAdvice() + { + discardSolutions(); + } + + void + defineBinding (Literal topic) + { + setBindingPattern (Binding(topic).addTypeGuard()); + maybe_rePublish(); + } + + private: + PointOfAdvice* storeCopy (AD const& advice_given); + static void releaseAdviceData (void*); + void maybe_rePublish (); + }; + + + /** + * Piece of Advice as incorporated into the AdviceSystem. + * This holder-object contains a copy of the advice data + * and is placed into the internal storage buffer; the + * advice index keeps a (type erased) pointer to serve + * any requests which happen to match the binding. + * + * @note the ptr-to-solution in the inherited PointOfAdvice + * is currently (5/10) not used, because this \em is + * already the solution. + */ + template + class ActiveProvision + : public PointOfAdvice + , boost::noncopyable + { + AD theAdvice_; + + public: + AD const& + getAdvice() const + { + return theAdvice_; + } + + protected: + ActiveProvision (PointOfAdvice const& refPoint, AD const& advice_given) + : PointOfAdvice(refPoint) + , theAdvice_(advice_given) + { + this->setSolution (this); // not used currently (5/10) + } + + friend class Provision; + }; + + + /* ==== memory management for Provision data ===== */ + + /** @internal function to copy advice into an internal buffer. + @return type erased pointer to the data holder created + @throw error::Fatal on allocation problems, plus anything + the advice data may throw during copy construction. */ + template + inline PointOfAdvice* + Provision::storeCopy (AD const& advice_given) + { + typedef ActiveProvision Holder; + void* storage = getBuffer(sizeof(Holder)); + try + { + Holder* storedProvision = new(storage) Holder (*this, advice_given); + manageAdviceData (storedProvision, &releaseAdviceData); + return storedProvision; + } + catch(...) + { + Symbol errID = lumiera_error(); + releaseBuffer (storage, sizeof(Holder)); + throw lumiera::error::Fatal ("Failure to store advice data", errID); + } + } + + + /** @internal assist the AdviceSystem with deallocating buffer storage. + * Problem is we need to know the exact size of the advice value holder, + * which information is available only here, in the fully typed context. + */ + template + inline void + Provision::releaseAdviceData (void* entry) + { + typedef ActiveProvision Holder; + if (entry) + { + Holder* obj = static_cast (entry); + obj->~Holder(); + releaseBuffer (entry, sizeof(Holder)); + } + } + + + /** @internal in case we've already published this provision, + * we temporarily need a new provision entry, to allow the + * AdviceSystem implementation to rewrite the internal index + */ + template + inline void + Provision::maybe_rePublish () + { + typedef const ActiveProvision AdviceProvision; + AdviceProvision* solution = static_cast (getSolution()); + + if (solution) // create copy of the data holder, using the new binding + publishProvision( + storeCopy (solution->getAdvice())); + } + + + + + + + + /** + * Access point for the advised entity (client). + * This is the interface intended for client code to request advice + * of a specific type and optionally limited to a special topic (binding). + * Instantiating an \c Request object automatically entails a registration + * with the AdviceSystem behind the scenes, and deleting it causes deregistration. + * Request objects may be instantiated and copied freely, and the binding pattern + * may be changed. The actual advice is accessed through the member function + * #getAdvice, which might return a default-constructed piece of advice data + * in case no specific advice has been provided yet. Accessing advice can be + * considered a lightweight operation, while creating/destroying advice + * causes an index operation and thus requires a lock. + * + * Creating an Request and changing the binding might fail, while the dtor + * is protected against failure (as you'd expect). Accessing advice can also + * be considered safe, given the concrete advice type can be default constructed + * without failure in case there isn't any advice data provided yet. + */ + template + class Request + : protected AdviceLink + { + typedef const ActiveProvision AdviceProvision; + + + /* == policy definitions == */ ////TODO: extract into policy classes + + AD const& + handleMissingSolution() const ///< @warning might segfault when used during shutdown + { + return NullValue::get(); + } + + + public: + explicit + Request (Literal bindingSpec =0) + : AdviceLink (Binding(bindingSpec).addTypeGuard()) + { + registerRequest(); + } + + ~Request() + { + deregisterRequest(); + } + + // copying Requests is allowed, using default + + + AD const& + getAdvice() const + { + AdviceProvision* solution = static_cast (this->getSolution()); + if (!solution) + return this->handleMissingSolution(); + else + return solution->getAdvice(); + } + + + void + defineBinding (Literal topic) + { + HashVal previous_bindingKey (hash_value(*this)); + setBindingPattern (Binding(topic).addTypeGuard()); + publishRequestBindingChange (previous_bindingKey); + } + }; + + + + + +}} // namespace lib::advice +#endif diff --git a/src/lib/advice/advice.cpp b/src/lib/advice/advice.cpp new file mode 100644 index 000000000..cbd70e764 --- /dev/null +++ b/src/lib/advice/advice.cpp @@ -0,0 +1,368 @@ +/* + Advice - generic loosely coupled interaction guided by symbolic pattern + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +/** @file advice.cpp + ** Implementation the AdviceSystem, to support the advice collaboration. + ** The AdviceSystem is implemented as singleton, but is never accessed directly + ** by clients participating in an advice collaboration. Rather, they use the + ** advice::Request and advice::Provision value classes as a frontend. While + ** these frontend classes are templated on the concrete advice type, the common + ** baseclass AdviceLink isn't, allowing the AdviceSystem to operate on type erased + ** PointOfAdvice entries. The protected access functions within AdviceLink are + ** implemented in this compilation unit and access the AdviceSystem singleton + ** defined here locally. + ** + ** \par memory management + ** Advice data, when added by an advice::Provision, is copied into a ActiveProvision, + ** which acts as a value holding buffer. This way, the provided advice data is copied + ** into storage managed by the AdviceSystem, allowing to access the data even after the + ** original advice::Provision went out of scope. + ** + ** But while the Provision is still alive, it may be used to set new advice, modify the + ** binding or even retract the given piece of advice. Thus we need a mechanism to link + ** the ActiveProvision (value holder) to its origin while the latter is still there. + ** Basically we'll use the PointOfAdvice::resolution_ pointer embedded within advice::Provision + ** to point to the ActiveProvision entry incorporated into the advice system. + ** (For advice::Request, the same pointer is used to link to the ActiveProvision yielding + ** the advice solution, if any). Handling the relation between Provision and ActiveProvision + ** this way entails some kind of "unofficial" ownership and is slightly incorrect, but seems + ** the most straight forward implementation. Thus each Provision cares for "his" advice and + ** just detaches when going away. Consequently, by default, advice provisions remain active + ** during the lifetime of the application. We'll see if this causes problems. + ** + ** @note when a Provision is copied, this hidden link is not shared with the copy, which + ** therefore behaves as if newly created with the same binding, but without providing Advice. + ** + ** \par implementing the allocations + ** The problem with copying and incorporating the ActiveProvision objects is the undetermined + ** size of these value holders, because the frontend objects are templated on the advice type, + ** while the AdviceSystem doesn't have any knowledge of the specific advice type. This advice + ** type is used to set a type guard predicate into each binding, but there is no way to + ** re-discover the specifically typed context; the type guards can only be checked for a match. + ** Thus we need the help of the frontend objects, which need to provide a deleter function + ** when providing concrete advice data; this deleter function will be saved as function pointer + ** so to be able to deallocate all advice data when the AdviceSystem is shut down. + ** + ** @todo This approach is closely related to the decision to use a single global index table + ** for managing all advice collaborations. An alternative would be to use either a separate + ** table for each type, or to store an additional type descriptor with this memory management + ** information into each "bucket", which can be assumed to manage entries dealing with the + ** same kind of advice data, because each binding automatically includes a type guard. + ** If we ever happen to get a significant amount of advice data, but only a small + ** number of different advice types, we should reconsider this optimisation. + ** + ** @todo rewrite the allocation to use Lumiera's MPool instead of heap allocations //////TICKET #609 + ** + ** \par synchronisation + ** While the frontend objects are deliberately \em not threadsafe, the lookup implementation + ** within the AdviceSystem uses a system wide advice::Index table and thus needs locking. + ** Besides the protection against corrupting the index, this also serves as memory barrier, + ** so that when a new advice solution is determined and set as a pointer within the matching + ** requests, this change is actually "committed" from cache to memory. But note, when using + ** advice::Request concurrently, you need to employ an additional read barrier to ensure + ** your thread/CPU picks up such newly determined solutions from main memory. Otherwise + ** you might even try to access superseded and already deleted advice data. + ** + ** @see advice.hpp + ** @see advice::Index + ** + */ + + +#include "lib/error.hpp" +#include "lib/advice.hpp" +#include "lib/advice/index.hpp" +#include "lib/del-stash.hpp" +#include "lib/singleton.hpp" +#include "lib/symbol.hpp" +#include "lib/sync.hpp" +#include "lib/util.hpp" +#include "include/logging.h" + +#include + +using lib::Symbol; +using lib::Singleton; +using util::unConst; + +typedef void (DeleterFunc)(void*); + + +namespace lib { +namespace advice { + + namespace { // ======= implementation of the AdviceSystem ============ + + /** + * the system-wide service to support the implementation + * of \em advice collaborations. Manages storage for + * provided advice data and maintains an index table + * to determine the advice solutions on request. + */ + class AdviceSystem + : public lib::Sync<> + , boost::noncopyable + { + + DelStash adviceDataRegistry_; + Index index_; + + public: + AdviceSystem() + : index_() + { + INFO (library, "Initialising Advice Index tables."); + } + + ~AdviceSystem() + { + INFO (library, "Shutting down Advice system."); + } + + + + /* == Advice data storage management == */ + + /** low-level allocation of storage to hold advice data + * @todo rewrite to use Lumiera's block allocator / memory pool /////////////////////////////////TICKET #609 + * @warning the raw allocation and deallocation is \em not protected + * by the AdviceSystem monitor. Currently we don't need + * locking (heap allocation), but any custom allocator + * will have to care for its own locking! + */ + void* + allocateBuffer(size_t siz) + { + try { return new char[siz]; } + + catch(std::bad_alloc&) + { + throw error::Fatal("Unable to store Advice due to memory exhaustion"); + } + } + + void + releaseBuffer (void* buff, size_t) /////////////////////////////////TICKET #609 + { + delete[] (char*)buff; + } + + void + manageAdviceData (PointOfAdvice* entry, DeleterFunc* how_to_delete) + { + Lock sync (this); + adviceDataRegistry_.manage (entry, how_to_delete); + } + + private: + void + discardEntry (PointOfAdvice* storedProvision) ///< @note to be invoked from a locked scope + { + if (storedProvision) + { + adviceDataRegistry_.kill (storedProvision); + } } + + + + public: + /* == forward additions and retractions to the index == */ + + void + publishRequestBindingChange(PointOfAdvice & req, + HashVal previous_bindingKey) + { + Lock sync (this); + index_.modifyRequest(previous_bindingKey, req); + } + + void + registerRequest(PointOfAdvice & req) + { + Lock sync (this); + index_.addRequest (req); + } + + void + deregisterRequest(PointOfAdvice const& req) + { + try + { + Lock sync (this); + index_.removeRequest (req); + } + + catch(...) + { + Symbol errID = lumiera_error(); + WARN (library, "Problems on deregistration of advice request: %s", errID.c()); + } + } + + + void + publishProvision (PointOfAdvice* newProvision, const PointOfAdvice* previousProvision) + { + Lock sync (this); + + if (!previousProvision && newProvision) + index_.addProvision (*newProvision); + else + if (previousProvision && newProvision) + index_.modifyProvision (*previousProvision, *newProvision); + else + if (previousProvision && !newProvision) + index_.removeProvision (*previousProvision); + + discardEntry (unConst(previousProvision)); + } + + void + discardSolutions (const PointOfAdvice* existingProvision) + { + Lock sync (this); + + if (existingProvision) + index_.removeProvision (*existingProvision); + + discardEntry (unConst(existingProvision)); + } + }; + + + /** hidden implementation-level access to the AdviceSystem */ + Singleton aSys; + + + } //(End) AdviceSystem implementation + + + + + + + /* ====== AdviceLink : access point for Provisions and Requests ====== */ + + + /** allocate raw storage for a buffer holding the actual piece of advice. + * We need to manage this internally, as the original advice::Provision + * may go out of scope, while the advice information as such remains valid. + * @note the special twist is the size of the buffer depending on the actual + * advice type, which type information we need to erase for tracking all + * advice provisions and requests through an generic index datastructure. + * @throws error::Fatal on allocation failure + */ + void* + AdviceLink::getBuffer(size_t siz) + { + return aSys().allocateBuffer(siz); + } + + + void + AdviceLink::releaseBuffer (void* buff, size_t siz) + { + aSys().releaseBuffer(buff, siz); + } + + + /** Store a descriptor record to take ownership of the given allocation. + * Problem is we need to know the exact size of the advice value holder, + * which information is available initially, when the advice data is + * copied into the system. The knowledge about the size of the allocation + * is embodied into the deleter function. This allows later to discard + * entries without needing to know their exact type. + */ + void + AdviceLink::manageAdviceData (PointOfAdvice* entry, DeleterFunc* how_to_delete) + { + aSys().manageAdviceData (entry,how_to_delete); + } + + + + + /** when the Provision actually sets advice data, this is copied + * into an internal buffer within the AdviceSystem. We then use the + * Index to remember the presence of this advice data and to detect + * possible matches with existing advice::Request entries. + * @param adviceData pointer to the copied data, + * actually pointing to an ActiveProvision + * @return pointer to an superseded old provision entry, + * which the caller then needs to de-allocate. + * The caller is assumed to know the actual type + * and thus the size of the entry to deallocate. + * Returning \c NULL in case no old entry exists. + */ + void + AdviceLink::publishProvision (PointOfAdvice* newProvision) + { + const PointOfAdvice* previousProvision (getSolution()); + this->setSolution (newProvision); + + aSys().publishProvision (newProvision, previousProvision); + } + + + /** when advice is retracted explicitly, + * after removing the provision index entry + * we also need to re-process any requests + * which happen to match our binding... + * @return pointer to the existing provision entry, + * to be deallocated by the caller, which + * is assumed to know it's exact type. + */ + void + AdviceLink::discardSolutions () + { + const PointOfAdvice* existingProvision (getSolution()); + this->setSolution ( NULL ); + aSys().discardSolutions (existingProvision); + } + + + void + AdviceLink::publishRequestBindingChange(HashVal previous_bindingKey) + { + aSys().publishRequestBindingChange (*this, previous_bindingKey); + } + + + void + AdviceLink::registerRequest() + { + aSys().registerRequest (*this); + } + + + void + AdviceLink::deregisterRequest() + { + aSys().deregisterRequest (*this); + } + + + + + +}} // namespace lib::advice diff --git a/src/lib/advice/binding.cpp b/src/lib/advice/binding.cpp new file mode 100644 index 000000000..c123f04d7 --- /dev/null +++ b/src/lib/advice/binding.cpp @@ -0,0 +1,194 @@ +/* + Binding - pattern defining a specific attachment to the Advice system + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/advice/binding.hpp" +#include "lib/symbol.hpp" +#include "lib/util.hpp" + +#include +#include +#include + + +using lib::Literal; +using util::isnil; + +using boost::regex; +using boost::smatch; +using boost::sregex_iterator; +using boost::match_continuous; +using boost::hash_combine; +using boost::lexical_cast; + + +namespace lib { +namespace advice { + + LUMIERA_ERROR_DEFINE (BINDING_PATTERN_SYNTAX, "Unable to parse the given binding pattern definition"); + + + + + + /////////////////////TICKET #613 : centralise generally useful RegExps + namespace{ // Implementation details + + const string matchSym = "(\\w+(?:[\\.\\-]\\w+)*)"; + const string matchArg = "\\(\\s*"+matchSym+"?\\s*\\)"; + regex findPredicate ("\\s*"+matchSym+"("+matchArg+")?\\s*,?"); ///< \c sym(arg), groups: [symbol, parenthesis, argument symbol] + + /** detect the \em arity of an predicate, as matched by #findPredicate. + * Currently, we don't really parse predicate logic notation and thus we + * just distinguish nullary predicates (no argument) and predicates with + * one single constant argument. */ + inline uint + detectArity (smatch const& match) + { + if (!match[2].matched) return 0; // no parenthesis at all + if (!match[3].matched) return 0; // empty parenthesis + + // later we could analyse the argument in detail here... + return 1; // but now we just accept a single constant symbol + } + } + + + void + Binding::parse_and_append (Literal lit) + { + string def(lit); + string::const_iterator end_of_last_match = def.begin(); + + sregex_iterator end; + sregex_iterator pos (def.begin(),def.end(), findPredicate, + match_continuous); // continuous: don't allow garbage *not* matched by the RegExp + while (pos != end) + { + smatch match = *pos; + atoms_.insert (Atom (match[1], detectArity(match), match[3])); + end_of_last_match = match[0].second; + ++pos; + } + + if ( end_of_last_match !=def.end() + && *end_of_last_match !='.' + ) // if the match did *not stop at the end of the pattern definition list + throw lumiera::error::Invalid ("Trailing garbage in binding pattern definition" ///////////////TICKET #197 should include the garbage, i.e. where the parsing stops + , LUMIERA_ERROR_BINDING_PATTERN_SYNTAX); + } + + + Binding::Binding () + : atoms_() + { } + + Binding::Binding (Literal spec) + { + if (!isnil(spec)) + parse_and_append (spec); + } + + + void + Binding::addPredicate (Literal spec) + { + REQUIRE (spec); + parse_and_append (spec); + } + + + + Binding::operator string() const + { + string repr("Binding["); + typedef NormalisedAtoms::const_iterator AIter; + AIter end = atoms_.end(); + AIter pos = atoms_.begin(); + for ( ; pos!=end ; ++pos) + repr += string(*pos)+", "; + + if (0 < atoms_.size()) + repr.resize(repr.size()-2); + + repr += "]"; + return repr; + } + + + Binding::Atom::operator string() const + { + return sym_+"/"+lexical_cast (ari_) + +"("+arg_+")"; + } + + + HashVal + Binding::calculateHash() const + { + HashVal hash=0; + + typedef NormalisedAtoms::const_iterator AIter; + AIter pos = atoms_.begin(); + AIter end = atoms_.end(); + for ( ; pos!=end ; ++pos) + { + hash_combine (hash, pos->sym()); + hash_combine (hash, pos->arity()); + hash_combine (hash, pos->arg()); //////////////TICKET #615 : not in final version with variable arguments + } + + return hash; + } + + + /** bindings are considered equivalent if, + * after normalisation, their respective definitions are identical. + * @note for bindings without variable arguments, equivalence and matching + * always yield the same results. Contrary to this, two bindings with + * some variable arguments could match, without being defined identically. + * For example \c pred(X) matches \c pred(u) or any other binding of the + * form \c pred() ////TICKET #615 not yet implemented + */ + bool + operator== (Binding const& b1, Binding const& b2) + { + if (b1.atoms_.size() != b2.atoms_.size()) + return false; + + ASSERT (b1.atoms_.size() == b2.atoms_.size()); + + typedef Binding::NormalisedAtoms::const_iterator Iter; + Iter end = b1.atoms_.end(); + Iter p1 = b1.atoms_.begin(); + Iter p2 = b2.atoms_.begin(); + + for ( ; p1!=end; ++p1, ++p2 ) + if (! p1->identical(*p2)) + return false; + + return true; + } + + + +}} // namespace lib::advice diff --git a/src/lib/advice/binding.hpp b/src/lib/advice/binding.hpp new file mode 100644 index 000000000..23d2b5ae4 --- /dev/null +++ b/src/lib/advice/binding.hpp @@ -0,0 +1,301 @@ +/* + BINDING.hpp - pattern defining a specific attachment to the Advice system + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +/** @file binding.hpp + ** A pattern to define and identify a specific attachment to the Advice system. + ** This pattern is comprised of a predicate list and intended to be matched or unified + ** against a similar pattern associated with the attachment of a possible collaboration partner. + ** Semantically, this list of atoms forms an conjunction of predicates to be resolved against + ** similar predicates of the partner. Informally, when two entities attach to the Advice system, + ** each specifying a binding, they can be paired up if any condition included into the binding + ** holds true for both sides. + ** + ** Typically, a binding includes a \em type-guard predicate \c advice.type.xx where \c xx is an + ** identifier denoting a type used within an instantiation of the Advice collaboration, i.e. a type + ** used as advice value in a instantiation of the PointOfAdvice template. Besides the type guard, + ** a binding may narrow down the topic of the advice by providing further predicates. This allows for + ** Advice collaborations targeted at a more specific topic. The goal and intention behind this Advice + ** system is to allow collaboration of entities without requiring them to be tightly coupled. Indeed, + ** the only dependency besides the common type used as advice is to know any specific topic used + ** within the binding. Thus, and advisor entity could put up a piece of advice, i.e. a value of + ** the advice type, and another client entity (the advised entity) could pick up this value + ** without the need to now anything about the advisor. + ** + ** \par implementation notes + ** Any binding will be normalised prior to further processing. This normalisation is based + ** on ordering by predicate symbol and arity. Patterns just comprised of constant symbols + ** (nullary atoms) can even be condensed into a single hash value, which allows for fast + ** match checking. For each pattern, we provide a matcher functor, allowing to check + ** a match against this pattern. In case of the mentioned symbol-only patterns, + ** this matcher will just hold the hash value of the normalised pattern. + ** + ** The advice system uses a binding index datastructure to keep track of any participating + ** patterns and especially of the matching pairs. Actually, this datastructure needs to store + ** only these matcher functors; thus, for a new binding to be used within the advice system, + ** the symbolic definition is parsed, then normalised and finally, after creating the matcher + ** functor, the full pattern definition can be discarded. + ** + ** @note as of 4/2010 this is an experimental setup and implemented just enough to work out + ** the interfaces. Ichthyo expects this collaboration service to play a central role + ** at various places within proc-layer. + ** @todo for now, \em only the case of a completely constant (ground) pattern is implemented. + ** Later we may consider to extend the binding patterns to allow variables, which, on match + ** could be fed as parameters to the bound advice. But this extension requires to extend + ** the simple hash-based match check to an actual unification of the patterns. ///TICKET #615 + ** + ** @see advice.hpp + ** @see advice-binding-pattern-test.cpp + ** + */ + + +#ifndef LIB_ADVICE_BINDING_H +#define LIB_ADVICE_BINDING_H + + +#include "lib/error.hpp" +#include "lib/symbol.hpp" +#include "lib/query.hpp" + +#include +#include +#include + +namespace lib { +namespace advice { + + using std::string; + + typedef size_t HashVal; + + LUMIERA_ERROR_DECLARE (BINDING_PATTERN_SYNTAX); ///< Unable to parse the given binding pattern definition + + + + /** + * Conjunction of predicates to be matched + * against a collaboration partner for establishing + * an Advice connection. The binding is defined by a + * textual spec in prolog-like syntax. The internal + * representation is immediately \em normalised. + * Typically the goal is just to create a #Matcher + * (Functor) to be stored for later match checks + * TODO type comment + */ + class Binding + { + + /** + * single predicate + * as part of an advice binding pattern + */ + class Atom + { + uint ari_; + string sym_; + string arg_; + + public: + explicit + Atom (string const& symbol ="nil", uint arity =0, string const& arg ="") + : ari_(arity), sym_(symbol), arg_(arg) + { } + + string const& sym() const { return sym_; } + string const& arg() const { return arg_; } + uint arity() const { return ari_; } + + operator string() const; + + bool + identical (Atom const& oa) const + { + return ari_ == oa.ari_ + && sym_ == oa.sym_ + && arg_ == oa.arg_; + } + + int + compare (Atom const& oa) const ///< @note when #compare returns 0, the corresponding Atom counts as duplicate + { + int res; + if (0 != (res=sym().compare (oa.sym()))) return res; + if (0 != (res=arity() - (oa.arity()))) return res; + return arg().compare (oa.arg()); /////TODO: in the final version, when we'll allow for variable arguments + } /////////: and unification, then variable arguments must not be part of + /////////: the comparison, otherwise the matching by hash will break! + friend bool + operator< (Atom const& a1, Atom const& a2) + { + return a1.compare(a2) < 0; + } + }; + + + typedef std::set NormalisedAtoms; + + NormalisedAtoms atoms_; + + + public: + /** + * Functor object for matching against another Binding. + * Contains precompiled information necessary for + * determining a match. + * @note Matcher is POD, copyable, no-throw + */ + class Matcher + { + HashVal bindingHash_; + + + Matcher (HashVal ha) + : bindingHash_(ha) + { } + + friend class Binding; + + + public: + bool matches (Binding const& obi) const; + bool matches (Binding::Matcher const& oma) const; + + friend HashVal hash_value (Matcher const&); + }; + + + + + /** create the empty binding, equivalent to \c true */ + Binding(); + + /** create the binding as defined by the given textual definition. + * @note implicit type conversion deliberately intended */ + Binding (Literal spec); + + /*-- Binding is default copyable --*/ + + /** extend the definition of this binding + * by adding a predicate according to the + * given textual definition */ + void addPredicate (Literal spec); + + template + Binding const& addTypeGuard(); + + + Matcher buildMatcher() const; + HashVal calculateHash() const; + + operator string() const; + + friend bool operator== (Binding const&, Binding const&); + + + private: + /** internal: parse into atoms, and insert them */ + void parse_and_append (Literal def); + }; + + + inline std::ostream& + operator<< (std::ostream& os, Binding const& bi) + { + return os << string(bi); + } + + template + inline Binding const& + Binding::addTypeGuard() + { + atoms_.insert (Atom ("advice.type."+lumiera::query::buildTypeID())); + return *this; + } + + + + + /* === equality comparison and matching === */ + + + inline bool + operator!= (Binding const& b1, Binding const& b2) + { + return ! (b1 == b2); + } + + + inline bool + matches (Binding const& b1, Binding const& b2) + { + return b1.buildMatcher().matches (b2); + } + + inline bool + matches (Binding::Matcher const& m1, Binding::Matcher const& m2) + { + return m1.matches (m2); + } + + + inline Binding::Matcher + Binding::buildMatcher() const + { + return Matcher (this->calculateHash()); + } + + + + /* == access hash values used for matching == */ + + inline bool + Binding::Matcher::matches (Binding const& obi) const + { + return bindingHash_ == obi.calculateHash(); + } + + inline bool + Binding::Matcher::matches (Binding::Matcher const& oma) const + { + return bindingHash_ == hash_value(oma); + } + + inline HashVal + hash_value (Binding::Matcher const& bm) + { + return bm.bindingHash_; + } + + inline HashVal + hash_value (Binding const& bi) + { + return bi.calculateHash(); + } + + + + + + +}} // namespace lib::advice +#endif diff --git a/src/lib/advice/index.hpp b/src/lib/advice/index.hpp new file mode 100644 index 000000000..7d3b07fc0 --- /dev/null +++ b/src/lib/advice/index.hpp @@ -0,0 +1,594 @@ +/* + INDEX.hpp - data structure for organising advice solutions and matching + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +/** @file index.hpp + ** Implementation datastructure for use by the Advice system. + ** To support the \em Advice collaboration, it is necessary to match advice requests with + ** existing advice provisions. Each successful match creates an advice solution, resulting in + ** the bound piece of advice (data) to become visible to all the advised entities having placed + ** a matching advice request into the advice system. + ** + ** This header is intended to be incorporated as part of the advice system implementation (advice.cpp). + ** It is \em not usable as an external interface. But it is written in a rather self-contained manner, + ** in order to be testable in isolation. To this end, the actual PointOfAdvice entities being organised + ** by this index datastructure remain abstract (defined as template parameter), and are only manipulated + ** through the following functions: + ** - \c hash_value(POA) + ** - \c POA::getMatcher() + ** - \c POA::getSolution() + ** - \c POA::setSolution(solution*) + ** + ** \par implementation notes + ** The advice binding index is implemented by two hashtables holding Binding::Matcher entries. + ** Each entry associates a back-link to the corresponding POA (PointOfAdvice), which is assumed + ** to be maintained outside the index. PointOfAdvice is an type-erased interface baseclass. + ** Actually the advice system will have to deal with concrete advice::Request and advice::Provision + ** objects, which are templated to a specific advice type; but this specifically typed context + ** is kept on the interface level (advice.hpp) and the type information is stripped before + ** calling into the actual implementation, so the index can be implemented generic. + ** + ** While both hashtables are organised by the binding pattern hash, the individual buckets are + ** coded explicitly as ProvisionCluster and RequestCluster -- both based on a vector of entries. + ** In case of the provisions, there is a stack-like order, inasmuch additions happen at the back + ** and solutions are always searched starting from the end. Because of the basic structure of + ** a binding match, solutions are possible \only between provision/request - clusters with the + ** same hash value (which is based on the predicate symbols within the patterns to match). Thus, + ** in case of changing an existing request or solution, the internal handling is different, + ** depending on the new value to belong or don't belong to the same cluster (hash code). + ** It's possible (for patterns including variables) that an entry leading to a solution with + ** the old provision doesn't match a new provision (and vice versa); thus we'll have to traverse + ** the contents of the whole cluster, find all old solutions, match against the new counterpart + ** and treating those entries \em not matching with the new value as if they where completely + ** newly added entries. In case we don't find any solution, the entries are supposed to be + ** implemented such as to fall back to an default solution automatically (when receiving + ** a \c NULL solution) + ** + ** @note as of 4/2010 this is an experimental setup and implemented just enough to work out + ** the interfaces. Ichthyo expects this collaboration service to play a central role + ** later at various places within proc-layer. + ** @note for now, \em only the case of a completely constant (ground) pattern is implemented. + ** Later we may consider to extend the binding patterns to allow variables. The mechanics + ** of the index are designed right from start to support this case (and indeed the index + ** could be much simpler if it wasn't to deal with this foreseeable additional complexity: + ** When a pattern contains variables, then even within one bucket of the hashtable there + ** might be non-matching entries. Each individual pair of (provision, request) has to be + ** checked explicitly to determine a match. /////////////////////////TICKET #615 + ** + ** @see advice.hpp + ** @see binding.hpp + ** @see advice-index-test.cpp + ** @see advice-binding-pattern-test.cpp + ** @see advice-basics-test.cpp + ** + */ + + +#ifndef LIB_ADVICE_INDEX_H +#define LIB_ADVICE_INDEX_H + + +#include "lib/error.hpp" +#include "lib/advice/binding.hpp" +#include "lib/symbol.hpp" +#include "include/logging.h" +#include "lib/iter-adapter-stl.hpp" +#include "lib/util-foreach.hpp" +#include "lib/util.hpp" + +#include +#include +#include +#include + +namespace lib { +namespace advice { + + using std::tr1::placeholders::_1; + using std::tr1::unordered_map; + using lib::iter_stl::eachVal; + using lib::iter_stl::eachElm; + using util::for_each; + using util::contains; + using util::unConst; + using lib::Literal; + using std::string; + using std::vector; + using std::pair; + using std::ostream; + using std::cout; + using std::endl; + + using namespace lumiera; + + + + + /** + * Index datastructure for organising advice solutions. + * Based on two hashtables for advice provisions and requests, + * the index allows to add, modify and remove entities of these + * two kinds. Each of these mutating operations immediately + * re-computes the advice solutions and publishes the results + * by invoking the \c setSolution() function on the + * corresponding PointOfAdvice entity. + * + * @note element \em identity is defined in terms of pointing + * to the same memory location of a POA (point of advice). + * Thus e.g. #hasProvision means this index holds an entry + * pointing to exactly this given data entity. + * @note the implementation of modifying a Request entry + * explicitly relies on that definition of equality. + * @note the diagnostic API is mainly intended for unit testing + * and \em not implemented with focus on performance. + * + * \par Exception safety + * Adding new registrations might throw error::Fatal or bad_alloc. + * The addition in this case has no effect and the index remains valid. + * The other mutating operations are NO_THROW, given that Binding::Matcher + * is a POD and std::vector fulfils the guarantee for POD content elements. + */ + template + class Index + { + + + struct Entry + : pair + , boost::equality_comparable > + { + explicit + Entry (POA& elm) + : pair (elm.getMatcher(), &elm) + { } + + // using default-copy, thus assuming copy is NO_THROW + + friend bool + operator== (Entry const& a, Entry const& b) + { + return a.second == b.second; + } + + friend bool + operator== (Entry const& a, POA const& p) + { + return a.second == &p; + } + + friend ostream& + operator<< (ostream& os, Entry const& ent) + { + return os << "E-"< " << ent.second ; + } + }; + + + typedef vector EntryList; + typedef typename EntryList::iterator EIter; + + + struct Cluster + { + EntryList elms_; + + size_t + size() const + { + return elms_.size(); + } + + void + append (POA& elm) + { + REQUIRE (!contains (elm), "Duplicate entry"); + try { elms_.push_back (Entry(elm)); } + + catch(std::bad_alloc&) + { + throw error::Fatal("AdviceSystem failure due to exhausted memory"); + } + } + + void + overwrite (POA const& oldRef, POA& newElm) + { + EIter pos = std::find (elms_.begin(),elms_.end(), oldRef); + REQUIRE (pos!=elms_.end(), "Attempt to overwrite an entry which isn't there."); + REQUIRE_IF (&oldRef != &newElm, !contains (newElm), "Duplicate entry"); + + *pos = Entry(newElm); + + REQUIRE_IF (&oldRef != &newElm, !contains (oldRef), "Duplicate entry"); + } + + void + remove (POA const& refElm) + { + EIter pos = std::find (elms_.begin(),elms_.end(), refElm); + if (pos!=elms_.end()) + elms_.erase(pos); + + ENSURE (!contains (refElm), "Duplicate entry"); + } + + bool + contains (POA const& refElm) + { + for (EIter i=elms_.begin(); i!=elms_.end(); ++i) + if (*i == refElm) return true; + return false; + } + + void + dump() ///< debugging helper: Cluster contents --> STDOUT + { + cout << "elmList("<< elms_.size()<<")" << endl; + for (EIter i=elms_.begin(); i!=elms_.end(); ++i) + cout << "E...:"<< (*i) << endl; + } + + RangeIter + allElms () + { + return eachElm (elms_); + } + }; + + + struct ProvisionCluster + : Cluster + { + POA* + find_latest_solution (POA& requestElm) + { + typedef typename EntryList::reverse_iterator RIter; + Binding::Matcher pattern (requestElm.getMatcher()); + for (RIter ii=this->elms_.rbegin(); + ii!=this->elms_.rend(); + ++ii ) + if (ii->first.matches (pattern)) + return ii->second; + + return NULL; + } + + void + publish_latest_solution (POA& requestElm) + { + POA* solution = find_latest_solution (requestElm); + if (solution) + // found the most recent advice provision satisfying the (new) request + // thus publish this new advice solution into the request object + requestElm.setSolution (solution); + else + requestElm.setSolution ( NULL ); + // report "no solution" which causes a default solution to be used + } + }; + + struct RequestCluster + : Cluster + { + void + publish_all_solutions (POA& provisionElm) + { + Binding::Matcher pattern (provisionElm.getMatcher()); + for (EIter ii=this->elms_.begin(); + ii!=this->elms_.end(); + ++ii ) + if (pattern.matches (ii->first)) + // the given (new) advice provision satisfies this request + // thus publish this new advice solution into the request object + ii->second->setSolution (&provisionElm); + } + + void + retract_all_solutions (POA const& oldProv, ProvisionCluster& possibleReplacementSolutions) + { + Binding::Matcher pattern (oldProv.getMatcher()); + for (EIter ii=this->elms_.begin(); + ii!=this->elms_.end(); + ++ii ) + if (pattern.matches (ii->first)) + // the old advice provision (to be dropped) satisfied this request + // which thus needs to be treated anew (could cause quadratic complexity) + possibleReplacementSolutions.publish_latest_solution (*(ii->second)); + } + + void + rewrite_all_solutions (POA const& oldProv, POA& newProv, ProvisionCluster& possibleReplacementSolutions) + { + Binding::Matcher oldPattern (oldProv.getMatcher()); + Binding::Matcher newPattern (newProv.getMatcher ()); + for (EIter ii=this->elms_.begin(); + ii!=this->elms_.end(); + ++ii ) + if (newPattern.matches (ii->first)) + ii->second->setSolution (&newProv); + else + if (oldPattern.matches (ii->first)) + possibleReplacementSolutions.publish_latest_solution (*(ii->second)); + } + }; + + + + /* ==== Index Tables ===== */ + + typedef unordered_map RTable; + typedef unordered_map PTable; + + mutable RTable requestEntries_; + mutable PTable provisionEntries_; + + + + public: + + void + addRequest (POA& entry) + { + HashVal key (hash_value(entry)); + requestEntries_[key].append (entry); // might throw + provisionEntries_[key].publish_latest_solution (entry); + } + + /** @note explicitly relying on the implementation of \c == + * which checks only the memory location of the Request. + * Thus we can use the already modified Request to find + * the old entry within the index pointing to this Request. + * @param oKey the binding hash value prior to modification + */ + void + modifyRequest (HashVal oKey, POA& entry) + { + HashVal nKey (hash_value(entry)); + if (oKey != nKey) + { + requestEntries_[nKey].append (entry); // might throw + requestEntries_[oKey].remove (entry); + } + else + { // rewrite Entry to include the new binding + requestEntries_[nKey].overwrite (entry, entry); + } + provisionEntries_[nKey].publish_latest_solution (entry); + } + + void + removeRequest (POA const& refEntry) + { + HashVal oKey (hash_value(refEntry)); + requestEntries_[oKey].remove (refEntry); + } + + + void + addProvision (POA& entry) + { + HashVal key (hash_value(entry)); + provisionEntries_[key].append (entry); // might throw + requestEntries_[key].publish_all_solutions (entry); + } + + void + modifyProvision (POA const& oldRef, POA& newEntry) + { + HashVal oKey (hash_value(oldRef)); + HashVal nKey (hash_value(newEntry)); + if (oKey != nKey) + { + provisionEntries_[nKey].append (newEntry); // might throw, in which case it has no effect + provisionEntries_[oKey].remove (oldRef); + requestEntries_[nKey].publish_all_solutions (newEntry); + requestEntries_[oKey].retract_all_solutions (oldRef, provisionEntries_[oKey]); + } + else + { + provisionEntries_[nKey].overwrite (oldRef, newEntry); + requestEntries_[nKey].rewrite_all_solutions (oldRef,newEntry, provisionEntries_[nKey]); + } + } + + void + removeProvision (POA const& refEntry) + { + HashVal key (hash_value(refEntry)); + provisionEntries_[key].remove (refEntry); // NO_THROW + requestEntries_[key].retract_all_solutions (refEntry, provisionEntries_[key]); + } + + + /** @warning calling this effectively detaches any existing advice information, + * but doesn't clean up storage of advice provisions incorporated + * within the advice system in general. + */ + void + clear () + { + WARN (library, "Purging Advice Binding Index..."); + requestEntries_.clear(); + provisionEntries_.clear(); + } + + + + /* == diagnostics == */ + + /** validity self-check */ + bool isValid() const; + + size_t + size() const + { + return request_count() + provision_count(); + } + + size_t + request_count() const + { + return sumClusters (eachVal (requestEntries_)); + } + + size_t + provision_count() const + { + return sumClusters (eachVal (provisionEntries_)); + } + + bool + hasRequest (POA const& refEntry) const + { + return requestEntries_[hash_value(refEntry)].contains (refEntry); + } + + bool + hasProvision (POA const& refEntry) const + { + return provisionEntries_[hash_value(refEntry)].contains (refEntry); + } // note: even just lookup might create a new (empty) cluster; + // thus the tables are defined as mutable + + + private: + /** internal: sum element count over all + * clusters in the given hashtable */ + template + static size_t + sumClusters (IT ii) + { + size_t sum=0; + for ( ; ii; ++ii ) + sum += ii->size(); + return sum; + } + + void verify_Entry (Entry const&, HashVal) const; + void verify_Request (Entry const&, HashVal) const; + }; + + + + + + + + + + + + /* == Self-Verification == */ + + namespace { // self-check implementation helpers... + + LUMIERA_ERROR_DEFINE(INDEX_CORRUPTED, "Advice-Index corrupted"); + + struct SelfCheckFailure + : error::Fatal + { + SelfCheckFailure (Literal failure) + : error::Fatal (string("Failed test: ")+failure + ,LUMIERA_ERROR_INDEX_CORRUPTED) + { } + }; + } + + + + + /** Advice index self-verification: traverses the tables to check + * each entry is valid. Moreover, when a advice request has a stored solution + * which points back into the current advice provisions, this solution will be + * re-computed with the current data to prove it's still valid. + * @note expensive operation + */ + template + bool + Index::isValid() const + { + typedef typename RTable::const_iterator RTIter; + typedef typename PTable::const_iterator PTIter; + + try { + for (PTIter ii =provisionEntries_.begin(); + ii != provisionEntries_.end(); ++ii) + { + HashVal hash (ii->first); + Cluster& clu = unConst(ii->second); + for_each (clu.allElms(), &Index::verify_Entry, this, _1, hash); + } + for (RTIter ii=requestEntries_.begin(); + ii != requestEntries_.end(); ++ii) + { + HashVal hash (ii->first); + Cluster& clu = unConst(ii->second); + for_each (clu.allElms(), &Index::verify_Request, this, _1, hash); + } + return true; + } + + catch(SelfCheckFailure& failure) + { + lumiera_error(); + ERROR (library, "%s", failure.what()); + } + return false; + } + + + +#define VERIFY(_CHECK_, DESCRIPTION) \ + if (!(_CHECK_)) \ + throw SelfCheckFailure ((DESCRIPTION)); + + + template + void + Index::verify_Entry (Entry const& e, HashVal hash) const + { + VERIFY (hash == hash_value(e.first), "Wrong bucket, hash doesn't match bucket"); + VERIFY (e.second, "Invalid Entry: back-link is NULL"); + } + + template + void + Index::verify_Request (Entry const& e, HashVal hash) const + { + verify_Entry (e,hash); + POA& request = *(e.second); + const POA* solution (request.getSolution()); + if (solution && hasProvision(*solution)) + { + POA* currentSolution = provisionEntries_[hash].find_latest_solution (request); + VERIFY (e.first.matches (solution->getMatcher()),"stored advice solution not supported by binding match"); + VERIFY (bool(currentSolution), "unable to reproduce stored solution with the current provisions") + VERIFY (solution == currentSolution, "stored advice solution isn't the topmost solution for this request") + } + } + +#undef VERIFY + + +}} // namespace lib::advice +#endif diff --git a/src/lib/cmdline.cpp b/src/lib/cmdline.cpp index 89ebc2137..90335230e 100644 --- a/src/lib/cmdline.cpp +++ b/src/lib/cmdline.cpp @@ -35,9 +35,6 @@ using boost::algorithm::split; using boost::algorithm::join; using boost::algorithm::is_any_of; using boost::algorithm::token_compress_on; -using boost::regex; -using boost::smatch; -using boost::regex_search; using boost::regex; using boost::smatch; @@ -47,8 +44,8 @@ using boost::regex_search; #include -namespace util - { +namespace util { + /** create as a tokenised copy of the current commandline. * Note that argv[0] is always ignored. */ diff --git a/src/lib/del-stash.hpp b/src/lib/del-stash.hpp new file mode 100644 index 000000000..11dd537c6 --- /dev/null +++ b/src/lib/del-stash.hpp @@ -0,0 +1,252 @@ +/* + DEL-STASH.hpp - collect and execute deleter functions + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +*/ + + +/** @file del-stash.hpp + ** Collecting and finally triggering deleter functions. + ** This building block for custom memory management allows memorising how to kill an object. + ** Frequently, custom allocation schemes have to deal with type erased elements, where the + ** full typed context is only available during construction. When implementing these objects + ** without vtable, we need a reliable way of recalling the correct destructor to invoke. + ** Typically, such entry objects are to be de-allocated in bulk during shutdown, with + ** the possibility to deallocate some objects beforehand explicitly. + ** + ** The implementation is based on using a vector in a stack-like fashion, thus the + ** deallocation of individual objects might degenerate in performance. + ** + ** @see DelStash_test + ** @see AdviceSystem usage example + ** + */ + + + +#ifndef LIB_DEL_STASH_H +#define LIB_DEL_STASH_H + + +#include "lib/error.hpp" + +#include +#include +#include +#include +#include + + +namespace lib { + + using boost::disable_if_c; + using boost::is_same; + + /** + * Manage a collection of deleter functions. + * This component can memorise addresses and deleter functions + * and trigger deletion of single objects, or delete all objects + * on demand or automatically on shutdown. + * @warning clients must not add a given object more than once + */ + class DelStash + : boost::noncopyable + { + + typedef void KillFun(void*); + + /** + * @internal entry to store target pointer + * and the actual deleter function to use + */ + class Killer + { + void* target_; + KillFun* killIt_; + + public: + Killer(KillFun* f, void* t) + : target_(t) + , killIt_(f) + { + REQUIRE(f); + } + + void + trigger () + { + if (target_) + killIt_(target_); + target_ = NULL; // remember kill + } + + bool operator== (const void* target) const { return target_ == target; } + bool operator!= (const void* target) const { return target_ != target; } + + bool + isActive() const + { + return bool(target_); + } + }; + + + typedef std::vector Killers; + + Killers killers_; + + + public: + DelStash (size_t elms_to_reserve =0) + : killers_() + { + if (elms_to_reserve) + { + killers_.reserve (elms_to_reserve); + } + } + + ~DelStash () + { + try { killAll(); } + + catch(...) + { + Symbol errID = lumiera_error(); + WARN (memory, "Problems on de-allocation: %s", errID.c()); + } + } + + size_t + size () const + { + size_t activeEntries = 0; + size_t i = killers_.size(); + while (i) + if (killers_[--i].isActive()) + ++activeEntries; + return activeEntries; + } + + +#define __DONT_USE_THIS_OVERLOAD_FOR_VOID_POINTER_ \ + typename disable_if_c< is_same::value \ + ||is_same::value>::type* =0 + + + template + void + manage (TY* obj, __DONT_USE_THIS_OVERLOAD_FOR_VOID_POINTER_) + { + if (!obj) return; + REQUIRE (!isRegistered (obj)); + killers_.push_back (Killer (how_to_kill, obj)); + } + + template + void + manage (TY& obj, __DONT_USE_THIS_OVERLOAD_FOR_VOID_POINTER_) + { + REQUIRE (!isRegistered (&obj)); + killers_.push_back (Killer (how_to_kill, &obj)); + } + + template + void + manage (void* obj) + { + if (!obj) return; + REQUIRE (!isRegistered (obj)); + killers_.push_back (Killer (how_to_kill, obj)); + } + + void + manage (void* obj, KillFun* customDeleter) + { + if (!obj) return; + REQUIRE (!isRegistered (obj)); + killers_.push_back (Killer (customDeleter, obj)); + } + + + template + void + kill (TY* obj) + { + triggerKill (obj); + } // note: entry remains in the killer vector, + // but is disabled and can't be found anymore + + template + void + kill (TY& obj) + { + triggerKill (&obj); + } + + void + killAll () + { + size_t i = killers_.size(); + while (i) + killers_[--i].trigger(); + } + + + private: + /** trampoline function to invoke destructor + * of the specific target type */ + template + static void + how_to_kill (void* subject) + { + X* victim = static_cast (subject); + ENSURE (victim); + delete victim; + }; + + bool + isRegistered (const void* objAddress) + { + REQUIRE (objAddress); + return killers_.end() != findEntry (objAddress); + } + + Killers::iterator + findEntry (const void* obj) + { + REQUIRE (obj); + return std::find(killers_.begin(),killers_.end(), obj); + } + + void + triggerKill (void* objAddress) + { + Killers::iterator pos = findEntry (objAddress); + if (killers_.end() != pos) + pos->trigger(); + ENSURE (!isRegistered (objAddress), "duplicate deleter registration"); + } + }; + + + + +} // namespace lib +#endif diff --git a/src/lib/iter-adapter-stl.hpp b/src/lib/iter-adapter-stl.hpp index 63ec756cb..13e183113 100644 --- a/src/lib/iter-adapter-stl.hpp +++ b/src/lib/iter-adapter-stl.hpp @@ -278,6 +278,18 @@ namespace iter_stl { + /** @return Lumiera Forward Iterator + * to yield each Element from a STL container + */ + template + inline typename _SeqT::Range + eachElm (CON& coll) + { + typedef typename _SeqT::Range Range; + return Range (coll.begin(), coll.end()); + } + + /** @return Lumiera Forward Iterator to yield * each key of a map/multimap */ diff --git a/src/lib/query.cpp b/src/lib/query.cpp index 931d07ff4..ab143cd0b 100644 --- a/src/lib/query.cpp +++ b/src/lib/query.cpp @@ -66,12 +66,12 @@ namespace lumiera { if (is_upper (first)) id[0] = std::tolower (first); } - - namespace // Implementation details - { + //////////////////////TICKET #613 : centralise generally useful RegExps + namespace{ // Implementation details + map regexTable; Symbol matchArgument = "\\(\\s*([\\w_\\.\\-]+)\\s*\\),?\\s*"; @@ -128,7 +128,7 @@ namespace lumiera { * probably get for free when we embed a prolog system)... */ uint - countPraed (const string& q) + countPred (const string& q) { uint cnt (0); sregex_iterator end; diff --git a/src/lib/query.hpp b/src/lib/query.hpp index 65eba3869..99bba9ec9 100644 --- a/src/lib/query.hpp +++ b/src/lib/query.hpp @@ -77,7 +77,7 @@ namespace lumiera { * usable for ordering queries, as more predicates usually * mean more conditions, i.e. more constriction */ - uint countPraed (const string&); + uint countPred (const string&); const string extractID (Symbol, const string& termString); @@ -85,5 +85,16 @@ namespace lumiera { const string removeTerm (Symbol, string& termString); + template + const string + buildTypeID() + { + string typeID (typeid(TY).name()); + normaliseID (typeID); + return typeID; + } + + + }} // namespace lumiera::query #endif diff --git a/src/proc/asset.hpp b/src/proc/asset.hpp index 4fe2aa14c..900877aa4 100644 --- a/src/proc/asset.hpp +++ b/src/proc/asset.hpp @@ -183,7 +183,7 @@ namespace asset { const uint ver=1); - int compare (const Ident& other) const; + int compare (Ident const& other) const; /** @note equality ignores version differences */ bool operator== (Ident const& oi) const { return compare (oi) ==0; } @@ -308,7 +308,7 @@ namespace asset { * forwarded to the Asset comparison operators. * @note version info is irrelevant */ inline int - Asset::Ident::compare (const Asset::Ident& oi) const + Asset::Ident::compare (Asset::Ident const& oi) const { int res; if (0 != (res=category.compare (oi.category))) return res; @@ -320,7 +320,7 @@ namespace asset { /** promote subtype-ptr to PAsset, e.g. for comparing */ template inline const PcAsset - pAsset (const shared_ptr& subPtr) + pAsset (shared_ptr const& subPtr) { return static_pointer_cast (subPtr); } @@ -336,7 +336,7 @@ namespace asset { /** convenient for debugging */ - inline string str (const PcAsset& a) + inline string str (PcAsset const& a) { if (a) return string (*a.get()); diff --git a/src/proc/asset/category.hpp b/src/proc/asset/category.hpp index 53ed8e4fa..71a24eac4 100644 --- a/src/proc/asset/category.hpp +++ b/src/proc/asset/category.hpp @@ -102,7 +102,7 @@ namespace asset { inline ostream& - operator<< (ostream& os, const Category& cat) + operator<< (ostream& os, Category const& cat) { return os << string(cat); } diff --git a/src/proc/asset/struct-scheme.hpp b/src/proc/asset/struct-scheme.hpp index 69161ffbc..5428c171a 100644 --- a/src/proc/asset/struct-scheme.hpp +++ b/src/proc/asset/struct-scheme.hpp @@ -68,7 +68,7 @@ namespace asset{ - /* ==== structural asset ID scheme ==== */ /////////////////////////////////////////////TICKET #565 : better organization of this naming scheme + /* ==== structural asset ID scheme ==== */ /////////////////////////////////////////////TICKET #565 : better organisation of this naming scheme template struct StructTraits diff --git a/src/proc/mobject/session/defsregistry.hpp b/src/proc/mobject/session/defsregistry.hpp index f37f08109..0dc6242c5 100644 --- a/src/proc/mobject/session/defsregistry.hpp +++ b/src/proc/mobject/session/defsregistry.hpp @@ -96,7 +96,7 @@ namespace mobject { weak_ptr objRef; Record (const Query& q, const P& obj) - : degree (lumiera::query::countPraed (q)), + : degree (lumiera::query::countPred (q)), query (q), objRef (obj) { } diff --git a/tests/40components.tests b/tests/40components.tests index 75f3af8e6..241606571 100644 --- a/tests/40components.tests +++ b/tests/40components.tests @@ -3,7 +3,7 @@ TESTING "Component Test Suite: common and basic components" ./test-lib --group=c TEST "Hello test world" HelloWorld_test 3 <Binding[] +out-lit: aSymbol --->Binding[aSymbol/0()] +out-lit: a.compound_Symbol-with-various.parts --->Binding[a.compound_Symbol-with-various.parts/0()] +out-lit: trailing Garbage allowed. ☢☢ eat ☠☠☠ atomic ☠☠☠ waste ☢☢ --->Binding[Garbage/0(), allowed/0(), trailing/0()] +out-lit: a, list , of ,symbols. --->Binding[a/0(), list/0(), of/0(), symbols/0()] +out-lit: nullary(). --->Binding[nullary/0()] +out-lit: nullary( ) --->Binding[nullary/0()] +out-lit: nullary . --->Binding[nullary/0()] +out-lit: predicate( with-argument ) --->Binding[predicate/1(with-argument)] +out-lit: Binding[advice.type.n3lib6advice4test12_GLOBAL__N_111DummyAdviceE/0(), one/0(), three/1(four), two/0()] +out-lit: b0==Binding[] +out-lit: b1==Binding[cat1/0(), cat2/0()] +out-lit: b2==Binding[cat1/0(), cat2/0()] +out-lit: b2==Binding[advice.type.n7lumiera4TimeE/0(), cat1/0(), cat2/0(), cat3/1(zzz)] +return: 0 +END + + +TEST "Advice index implementation" AdviceIndex_test < : Yes out: HasNested_Core : No diff --git a/tests/42query.tests b/tests/42query.tests index 202b97618..717f0bde7 100644 --- a/tests/42query.tests +++ b/tests/42query.tests @@ -12,7 +12,7 @@ END TEST "normalise ID" QueryUtils_test normaliseID <instanceID); ASSERT ( ps[qx] == (*j)); - d = lumiera::query::countPraed (qx); + d = lumiera::query::countPred (qx); ASSERT ( d_prev <= d ); d_prev = d; } diff --git a/tests/lib/advice/advice-basics-test.cpp b/tests/lib/advice/advice-basics-test.cpp new file mode 100644 index 000000000..dcdde8992 --- /dev/null +++ b/tests/lib/advice/advice-basics-test.cpp @@ -0,0 +1,267 @@ +/* + AdviceBasics(Test) - basic behaviour of the Advice collaboration + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/advice.hpp" + +#include + +using std::rand; + + + +namespace lib { +namespace advice { +namespace test { + + namespace { // Some test classes using the advice system... + + + class TheAdvised + : private advice::Request + { + public: + TheAdvised (Literal topic =0) + { + rebind (topic); + } + + void + rebind (Literal topic) + { + defineBinding (topic); + } + + bool + got(int val) + { + return val == getAdvice(); + } + }; + + + class TheAdvisor + { + advice::Provision link_; + + public: + TheAdvisor (Literal topic =0) + { + rebind (topic); + } + + void + rebind (Literal topic) + { + link_.defineBinding (topic); + } + + void + publish (int val) + { + link_.setAdvice (val); + } + + void + clear() + { + link_.retractAdvice(); + } + }; + } + + + + /******************************************************************************* + * @test proof-of-concept for the Advice collaboration. + * Advice allows data exchange without coupling the participants tightly. + * This test demonstrates the basic expected behaviour in a simple but + * typical situation: two unrelated entities exchange a piece of data + * just by referring to a symbolic topic ID. + * + * @see advice.hpp + * @see AdviceSituations_test + * @see AdviceMultiplicity_test + * @see AdviceConfiguration_test + * @see AdviceBindingPattern_test + * @see AdviceIndex_test implementation test + */ + class AdviceBasics_test : public Test + { + + virtual void + run (Arg) + { + simpleExchange(); + createCollaboration(); + overwriting_and_retracting(); + } + + + /** @test the very basic usage situation: the advisor sets an information value + * and the advised entity picks it up. */ + void + simpleExchange() + { + TheAdvised client; // implicitly opens an request-for-advice + CHECK (client.got (0)); // no advice yet --> getting the default int() + + TheAdvisor server; // implicitly prepares an advice provision + CHECK (client.got (0)); // but as no advice was provided yet, nothing happens + + int rr (1 + (rand() % 1000)); + + server.publish (rr); // now an match is detected, creating an advice channel + CHECK (client.got (rr)); // ..so the client can pick up the provided advice value + } + + + /** @test multiple ways how to initiate the advice collaboration */ + void + createCollaboration() + { + TheAdvised client1 ("topic1()"); + TheAdvisor server2 ("topic2()"); + + int r1 (1 + (rand() % 1000)); + int r2 (1 + (rand() % 1000)); + + server2.publish (r2); + CHECK (client1.got(0)); + + TheAdvised client2 ("topic2()"); + CHECK (client2.got(r2)); + + TheAdvisor server1; + CHECK (client1.got(0)); + + server1.publish (r1); + CHECK (client1.got(0)); + CHECK (client2.got(r2)); + + server1.rebind ("topic1()"); + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); + } + + + /** @test changing the provided advice, finally retracting it, + * causing fallback on the default value. Any given advisor + * can connect to the advice system with multiple bindings + * consecutively. The connection has no identity beside this + * binding, so another server (advisor) can step into an + * existing connection and overwrite or retract the advice. + * Unless retracted, advice remains in the system, + * even after the advisor is gone. + */ + void + overwriting_and_retracting() + { + TheAdvised client1 ("slot1"); + TheAdvised client2 ("slot2"); + CHECK (client1.got(0)); + CHECK (client2.got(0)); + + int r1 (1 + (rand() % 1000)); + int r2 (1 + (rand() % 1000)); + + { + TheAdvisor server("slot1()"); + CHECK (client1.got(0)); + CHECK (client2.got(0)); + + server.publish (r1); + CHECK (client1.got(r1)); + CHECK (client2.got(0)); + + server.publish (r2); + CHECK (client1.got(r2)); + CHECK (client2.got(0)); + + server.rebind("slot2()"); + CHECK (client1.got(0)); + CHECK (client2.got(r2)); + } + + CHECK (client1.got(0)); + CHECK (client2.got(r2)); + + { + TheAdvisor anotherServer("slot1"); + CHECK (client1.got(0)); + CHECK (client2.got(r2)); + + anotherServer.publish (r1); + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); + } + + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); + + { + TheAdvisor yetAnotherServer("slot2"); + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); + + yetAnotherServer.publish (r1); + CHECK (client1.got(r1)); + CHECK (client2.got(r1)); + + yetAnotherServer.rebind("slot1"); + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); // ideally it should be 0, but actually we uncover the old provision + // the decision was to err for a simple implementation /////////TICKET #623 + yetAnotherServer.clear(); + CHECK (client1.got(r1)); // should be 0, but again the existing provision is uncovered + CHECK (client2.got(r2)); // should be 0 + + yetAnotherServer.rebind("slot2"); // no effect, because it doesn't provide advice anymore + CHECK (client1.got(r1)); + CHECK (client2.got(r2)); + + yetAnotherServer.publish (5); + CHECK (client1.got(r1)); + CHECK (client2.got(5)); + } + + CHECK (client1.got(r1)); + CHECK (client2.got(5)); + + client1.rebind("slot2"); + CHECK (client1.got(5)); + CHECK (client2.got(5)); + + client2.rebind("nonExistingSlot"); + CHECK (client1.got(5)); + CHECK (client2.got(0)); + } + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceBasics_test, "unit common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/advice/advice-binding-pattern-test.cpp b/tests/lib/advice/advice-binding-pattern-test.cpp new file mode 100644 index 000000000..285b3065e --- /dev/null +++ b/tests/lib/advice/advice-binding-pattern-test.cpp @@ -0,0 +1,217 @@ +/* + AdviceBindingPattern(Test) - cover pattern matching used to dispatch Advice + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/test/test-helper.hpp" + +#include "lib/advice.hpp" +#include "lib/time.h" + +#include + +using std::cout; +using std::endl; + + + +namespace lib { +namespace advice{ +namespace test { + + namespace { + class DummyAdvice { }; + } + + + + /******************************************************************************* + * @test the pattern matching machinery used to find an Advice solution. + * Each advice::Provision and advice::Request specifies a binding, used + * to discern various pieces of advice. Whenever patterns on the two sides + * match, an Advice channel is created, causing the advice provision to + * get visible to the advised entity. + * + * This test creates various patterns and verifies matching behaves + * as specified and documented. + * + * @todo partially unimplemented and thus commented out ////////////////////TICKET #605 + * + * @see advice.hpp + * @see AdviceBasics_test + * @see AdviceMultiplicity_test + * @see AdviceIndex_test implementation test + */ + class AdviceBindingPattern_test : public Test + { + + virtual void + run (Arg) + { + verifyPatternSyntax(); + verifyPatternNormalisation(); + verifyStaticMatch(); + verifyPreparedMatch(); + verifyDynamicMatch(); + } + + + void + verifyPatternSyntax() + { +#define _PARSE_AND_SHOW(_STR_) \ + cout << _STR_ << "\t--->" << Binding(_STR_) << endl; + + _PARSE_AND_SHOW (""); + _PARSE_AND_SHOW ("aSymbol"); + _PARSE_AND_SHOW ("a.compound_Symbol-with-various.parts"); + _PARSE_AND_SHOW ("trailing Garbage allowed. ☢☢ eat ☠☠☠ atomic ☠☠☠ waste ☢☢"); + _PARSE_AND_SHOW ("a, list , of ,symbols."); + _PARSE_AND_SHOW ("nullary()."); + _PARSE_AND_SHOW ("nullary( )"); + _PARSE_AND_SHOW ("nullary ."); + _PARSE_AND_SHOW ("predicate( with-argument )"); + + VERIFY_ERROR (BINDING_PATTERN_SYNTAX, Binding("no (valid definition here)")); + VERIFY_ERROR (BINDING_PATTERN_SYNTAX, Binding("predicate(with ☠☠☠ Garbage ☠☠☠")); + VERIFY_ERROR (BINDING_PATTERN_SYNTAX, Binding("§&Ω%€GΩ%€ar☠☠☠baäääääge")); + + Binding testBinding; + testBinding.addTypeGuard(); + testBinding.addPredicate("one two(), three( four )."); + + cout << testBinding << endl; + } + + + void + verifyPatternNormalisation() + { + Binding b0, b00; + Binding b1 ("cat1(), cat2()."); + Binding b2 (" cat2 cat1 ...."); + + cout << "b0==" << b0 << endl; + cout << "b1==" << b1 << endl; + cout << "b2==" << b2 << endl; + + + CHECK (b0 == b00); CHECK (b00 == b0); + CHECK (b1 == b2); CHECK (b2 == b1); + + CHECK (b0 != b1); CHECK (b1 != b0); + CHECK (b0 != b2); CHECK (b2 != b0); + + b2.addPredicate("cat1()"); // adding the same predicate multiple times has no effect + b2.addPredicate(" cat1 "); + CHECK (b1 == b2); + b2.addPredicate("cat3(zzz)"); + CHECK (b1 != b2); + + b1.addTypeGuard(); + CHECK (b1 != b2); + b1.addPredicate(" cat3( zzz ) "); + CHECK (b1 != b2); + b2.addTypeGuard(); + CHECK (b1 == b2); + + cout << "b2==" << b2 << endl; + } + + + void + verifyStaticMatch() + { + CHECK ( matches (Binding(), Binding())); + CHECK ( matches (Binding("pred()"), Binding("pred( ) "))); + + CHECK ( matches (Binding("pred(x)"), Binding("pred(x)"))); + CHECK (!matches (Binding("pred()"), Binding("pred(x)"))); + CHECK (!matches (Binding("pred(x)"), Binding("pred(y)"))); + + CHECK ( matches (Binding("pred(x), pred(y)"), Binding("pred(y), pred(x)"))); + CHECK (!matches (Binding("pred(x), pred(y)"), Binding("pred(y), pred(y)"))); + } + + + void + verifyPreparedMatch() + { + Binding b1 ("pred()"); + Binding b2 ("pred"); + Binding b3 ("pred, pred(x)"); + Binding b4 ("pred( x ) , pred()."); + CHECK ( matches (b1,b2)); + CHECK ( matches (b3,b4)); + + Binding::Matcher bm1 (b1.buildMatcher()); + Binding::Matcher bm2 (b2.buildMatcher()); + Binding::Matcher bm3 (b3.buildMatcher()); + Binding::Matcher bm4 (b4.buildMatcher()); + + CHECK (hash_value(b1) == hash_value(bm1)); + CHECK (hash_value(b2) == hash_value(bm2)); + CHECK (hash_value(b3) == hash_value(bm3)); + CHECK (hash_value(b4) == hash_value(bm4)); + + CHECK (hash_value(b1) != hash_value(b3)); + + CHECK ( matches (bm1,bm2)); + CHECK ( matches (bm3,bm4)); + CHECK (!matches (bm1,bm3)); + CHECK (!matches (bm2,bm4)); + } + + + /** @test match against patterns containing variables, + * verify the created solution arguments + * @todo this is a future extension and its not clear + * if we need it and what the exact semantics + * could be ///////////////////////////////TICKET #615 + */ + void + verifyDynamicMatch() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #615 + CHECK ( matches (Binding("pred(u)"), Binding("pred(X)"))); + CHECK ( matches (Binding("pred(f(u))"), Binding("pred(f(X))"))); + CHECK ( matches (Binding("pred(f(u,Y))"), Binding("pred(f(X,v))"))); + CHECK ( matches (Binding("pred(f(u,X))"), Binding("pred(f(X,v))"))); // the so called "standardisation apart" + + CHECK (!matches (Binding("pred(u,v)"), Binding("pred(X)"))); + CHECK (!matches (Binding("pred(f(u))"), Binding("pred(f(v))"))); + CHECK (!matches (Binding("pred(f(u))"), Binding("pred(g(X))"))); + CHECK (!matches (Binding("pred(f(u,v))"), Binding("pred(f(X,X))"))); + + //////TODO should also cover the difference between equality and match, which gets tangible only in conjunction with variables + +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #615 + } + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceBindingPattern_test, "unit common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/advice/advice-configuration-test.cpp b/tests/lib/advice/advice-configuration-test.cpp new file mode 100644 index 000000000..c4448a67a --- /dev/null +++ b/tests/lib/advice/advice-configuration-test.cpp @@ -0,0 +1,132 @@ +/* + AdviceConfiguration(Test) - cover the various policies to configure Advice + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +//#include "lib/test/test-helper.hpp" + +#include "lib/advice.hpp" +//#include "lib/p.hpp" +//#include "proc/assetmanager.hpp" +//#include "proc/asset/inventory.hpp" +//#include "proc/mobject/session/clip.hpp" +//#include "proc/mobject/session/track.hpp" +//#include "lib/meta/trait-special.hpp" +//#include "lib/util-foreach.hpp" +//#include "lib/symbol.hpp" + +//#include +//#include + +//using lib::test::showSizeof; +//using lib::test::randStr; +//using util::isSameObject; +//using util::and_all; +//using util::for_each; +//using util::isnil; +//using lib::Literal; +//using lib::Symbol; +//using lumiera::P; +//using std::string; +//using std::cout; +//using std::endl; + + + +namespace lib { +namespace advice { +namespace test { + + namespace { + } + + + + /******************************************************************************* + * @test this is a collection of tests to cover the configuration options + * available as policy arguments when establishing the collaboration. + * - default advice values, or blocking or throwing + * - using activation signals on both sides + * - dispatch without locking (TODO any chance we can cover this by test??) + * - more to come.... + * + * @todo partially unimplemented and thus commented out ////////////////////TICKET #605 + * + * @see advice.hpp + * @see AdviceBasics_test + * @see AdviceSituations_test + */ + class AdviceConfiguration_test : public Test + { + + virtual void + run (Arg) + { + checkDefaultAdvice(); + blockOnAdvice(); + checkSignals(); + } + + + /** @test typically, advice is a default constructible value, + * so there is a natural fallback in case no active advice + * provision exists. Alternatively we may specify to throw. + */ + void + checkDefaultAdvice() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 + } + + + /** @test when opening the advice collaboration, both sides may independently + * install a signal (callback functor) to be invoked when the actual + * advice solution gets established. + */ + void + checkSignals() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 + } + + + /** @test instead of allowing default advice values, both sides + * may enter a blocking wait until an advice solution is available. + * This is implemented as special case of using signals + */ + void + blockOnAdvice() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #605 + } + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceConfiguration_test, "unit common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/advice/advice-index-test.cpp b/tests/lib/advice/advice-index-test.cpp new file mode 100644 index 000000000..1e516c958 --- /dev/null +++ b/tests/lib/advice/advice-index-test.cpp @@ -0,0 +1,433 @@ +/* + AdviceIndex(Test) - cover the index datastructure used to implement Advice dispatch + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/advice/index.hpp" + +#include + +using lib::Literal; + + + +namespace lib { +namespace advice { +namespace test { + + namespace { // test support definitions + + /** + * Test dummy record, representing + * either a provision or an request. + * The advice binding is simulated by + * storing a pattern matcher, and for + * the case of the advice request, the + * solution is simulated by a \c TestPOA* + */ + struct TestPOA + { + TestPOA* solution_; + Binding::Matcher pattern_; + + explicit + TestPOA(Literal spec="missing") + : solution_(0) + , pattern_(Binding(spec).buildMatcher()) + { } + + bool + matches (Literal refSpec) const + { + return pattern_.matches (Binding(refSpec)); + } + + void + changeBinding (Literal newSpec) + { + pattern_ = Binding(newSpec).buildMatcher(); + } + + + /* == Adapter interface for use within the Index == */ + + void setSolution (TestPOA* p) { solution_ = p; } + const TestPOA* getSolution () const { return solution_;} + Binding::Matcher getMatcher () const { return pattern_; } + + friend HashVal + hash_value (TestPOA const& entry) + { + return hash_value (entry.pattern_); + } + }; + + + + + const uint MAX_TEST_ENTRIES = 10; + + std::vector testEntries(MAX_TEST_ENTRIES); + + + + /** convenience shortcut for writing testcases inline */ + inline TestPOA& + _entry (uint id, Literal spec) + { + REQUIRE (id < testEntries.size()); + + if (!testEntries[id].matches(spec)) + testEntries[id] = TestPOA(spec); + + return testEntries[id]; + } + + /** check if the given request got the denoted solution */ + inline bool + _hasSolution (uint req, uint prov) + { + REQUIRE (req < testEntries.size()); + REQUIRE (prov < testEntries.size()); + + return testEntries[req].solution_ == & testEntries[prov]; + } + + /** check if the given request holds a default solution */ + inline bool + _hasDefault (uint req) + { + REQUIRE (req < testEntries.size()); + return NULL == testEntries[req].solution_; + } + } + + typedef Index Index; + + + + /****************************************************************************************** + * @test the Advice system uses an index datastructure to support matching the bindings + * to get pairs of participants to connect by an individual advice channel. + * + * This test covers the properties of this implementation datastructure in isolation. + * We employ special \link TestPOA test entries \endlink, different from what is used + * in the advice system (contrary to the real thing we're not differentiating between + * advice request and advice provision, as for the test all we need is the possibility + * to set an "advice solution"). To use these test records, we create a specific + * instantiation of the advice::Index template solely for this test. + * + * @see advice.hpp + * @see AdviceBasics_test + * @see AdviceBindingPattern_test + */ + class AdviceIndex_test : public Test + { + + virtual void + run (Arg) + { + Index idx; + buildIndex (idx); + + addRequest (idx); + addProvision (idx); + removeRequest (idx); + retractProvision (idx); + modifyRequest (idx); + modifyProvision (idx); + + clearIndex (idx); + } + + + void + buildIndex (Index& idx) + { + CHECK (idx.isValid()); + CHECK (0 == idx.size()); + + idx.addRequest (_entry (1,"cat")); + idx.addRequest (_entry (2,"cat")); + idx.addRequest (_entry (3,"dog")); + CHECK (3 == idx.size()); + CHECK (3 == idx.request_count()); + CHECK (0 == idx.provision_count()); + + idx.addProvision (_entry (4,"dog")); + CHECK (4 == idx.size()); + CHECK (3 == idx.request_count()); + CHECK (1 == idx.provision_count()); + + CHECK (_hasDefault (1)); + CHECK (_hasDefault (2)); + CHECK (_hasSolution (3,4)); + CHECK (idx.isValid()); + } + + + void + addRequest (Index& idx) + { + CHECK (idx.isValid()); + uint req_cnt = idx.request_count(); + + idx.addRequest (_entry (5,"dog")); + idx.addRequest (_entry (6,"cat")); + + CHECK (idx.hasRequest (_entry (5,"dog"))); + CHECK (idx.hasRequest (_entry (6,"cat"))); + + CHECK (_hasDefault (6)); + CHECK (_hasSolution (5,4)); + CHECK (idx.isValid()); + CHECK (2 + req_cnt == idx.request_count()); + } + + + void + addProvision (Index& idx) + { + CHECK (idx.isValid()); + uint r_cnt = idx.request_count(); + uint p_cnt = idx.provision_count(); + + CHECK (_hasDefault (1)); + CHECK (_hasDefault (2)); + CHECK (_hasDefault (6)); + CHECK (_hasSolution (3,4)); + CHECK (_hasSolution (5,4)); + + idx.addProvision (_entry (7,"cat")); + CHECK (idx.hasProvision (_entry (7,"cat"))); + + CHECK (_hasSolution (1,7)); // all cats got the cat solution + CHECK (_hasSolution (2,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,4)); // dogs unaltered + CHECK (_hasSolution (5,4)); + CHECK (idx.isValid()); + CHECK (1 + p_cnt == idx.provision_count()); + CHECK (0 + r_cnt == idx.request_count()); + + idx.addProvision (_entry (8,"dog")); + + CHECK (_hasSolution (1,7)); // cats remain unaffected + CHECK (_hasSolution (2,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,8)); // all dogs got the new solution + CHECK (_hasSolution (5,8)); + CHECK (idx.isValid()); + CHECK (2 + p_cnt == idx.provision_count()); + CHECK (0 + r_cnt == idx.request_count()); + } + + + void + removeRequest (Index& idx) + { + CHECK (idx.isValid()); + uint r_cnt = idx.request_count(); + uint p_cnt = idx.provision_count(); + CHECK (_hasSolution (1,7)); + CHECK (_hasSolution (2,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,8)); + CHECK (_hasSolution (5,8)); + + CHECK ( idx.hasRequest (_entry (2,"cat"))); + + idx.removeRequest (_entry (2,"cat")); + + CHECK (!idx.hasRequest (_entry (2,"cat"))); + CHECK (p_cnt == idx.provision_count()); + CHECK (r_cnt-1 == idx.request_count()); + + CHECK (_hasSolution (1,7)); // no effect on the other requests + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,8)); + CHECK (_hasSolution (5,8)); + + idx.removeRequest (_entry (2,"cat")); // idempotent + CHECK (!idx.hasRequest (_entry (2,"cat"))); + CHECK (p_cnt == idx.provision_count()); + CHECK (r_cnt-1 == idx.request_count()); + CHECK (idx.isValid()); + } + + + void + retractProvision (Index& idx) + { + CHECK (idx.isValid()); + uint r_cnt = idx.request_count(); + uint p_cnt = idx.provision_count(); + CHECK (_hasSolution (1,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,8)); + CHECK (_hasSolution (5,8)); + + CHECK ( idx.hasProvision (_entry (4,"dog"))); + + idx.removeProvision (_entry (4,"dog")); + + CHECK (!idx.hasProvision (_entry (4,"dog"))); + CHECK (p_cnt-1 == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + + CHECK (_hasSolution (1,7)); // no effect on the solutions, because of the more recent dog solution 8 + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,8)); + CHECK (_hasSolution (5,8)); + + CHECK ( idx.hasProvision (_entry (8,"dog"))); + + idx.removeProvision (_entry (8,"dog")); + + CHECK (!idx.hasProvision (_entry (8,"dog"))); + CHECK (p_cnt-2 == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + + CHECK (_hasSolution (1,7)); // no effect on the cat solutions + CHECK (_hasSolution (6,7)); + CHECK (!_hasSolution (3,8)); + CHECK (!_hasSolution (5,8)); + CHECK (_hasDefault (3)); // but all dog requests reverted to default + CHECK (_hasDefault (5)); + + idx.removeProvision (_entry (8,"dog")); // idempotent + CHECK (!idx.hasProvision (_entry (8,"dog"))); + CHECK (p_cnt-2 == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + CHECK (idx.isValid()); + } + + + void + modifyRequest (Index& idx) + { + CHECK (idx.isValid()); + uint r_cnt = idx.request_count(); + uint p_cnt = idx.provision_count(); + CHECK (_hasSolution (1,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasDefault (3)); + CHECK (_hasDefault (5)); + + HashVal dogHash (hash_value (_entry (5,"dog"))); + + CHECK ( idx.hasRequest (_entry (5,"dog"))); + _entry (5,"dog").changeBinding("cat"); // transmogrify existing request into cat-request + CHECK (_hasDefault (5)); // of course this didn't change the solution + CHECK (!idx.hasRequest (_entry (5,"cat"))); // can't find it anymore because of changed binding + + idx.modifyRequest (dogHash, _entry (5,"cat")); + + CHECK ( idx.hasRequest (_entry (5,"cat"))); + CHECK (p_cnt == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + CHECK (_hasSolution (1,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasDefault (3)); + CHECK (_hasSolution (5,7)); // automatically got the current cat solution + } + + + void + modifyProvision (Index& idx) + { + CHECK (idx.isValid()); + uint r_cnt = idx.request_count(); + uint p_cnt = idx.provision_count(); + CHECK (_hasSolution (1,7)); + CHECK (_hasSolution (5,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasDefault (3)); + + CHECK ( idx.hasProvision (_entry (7,"cat"))); + CHECK (!idx.hasProvision (_entry (8,"dog"))); + + idx.modifyProvision (_entry (7,"cat"), _entry (8,"dog")); + CHECK (!idx.hasProvision (_entry (7,"cat"))); + CHECK ( idx.hasProvision (_entry (8,"dog"))); + CHECK (p_cnt == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + CHECK (_hasDefault (1)); + CHECK (_hasDefault (5)); + CHECK (_hasDefault (6)); + CHECK (_hasSolution (3,8)); + + idx.addProvision (_entry (7,"cat")); + idx.addProvision (_entry (9,"cat")); + CHECK (p_cnt+2 == idx.provision_count()); + CHECK (idx.hasProvision (_entry (7,"cat"))); + CHECK (idx.hasProvision (_entry (9,"cat"))); + CHECK (_hasSolution (1,9)); // all cats got the second cat solution + CHECK (_hasSolution (5,9)); + CHECK (_hasSolution (6,9)); + CHECK (_hasSolution (3,8)); // the dog is unaffected + + CHECK ( idx.hasProvision (_entry (7,"cat"))); + CHECK (!idx.hasProvision (_entry (4,"dog"))); + + idx.modifyProvision (_entry (7,"cat"), _entry (4,"dog")); + + CHECK (!idx.hasProvision (_entry (7,"cat"))); + CHECK ( idx.hasProvision (_entry (4,"dog"))); + CHECK (_hasSolution (1,9)); // cats unaffected, because we're changing a shadowed cat provision + CHECK (_hasSolution (5,9)); + CHECK (_hasSolution (6,9)); + CHECK (_hasSolution (3,4)); // but the dog got switched to the replaced-by-dog solution, + // because it was added later than the existing solution 8 + + // a switch within the same cluster ("cat") + idx.modifyProvision (_entry (9,"cat"), _entry (7,"cat")); + CHECK (!idx.hasProvision (_entry (9,"cat"))); + CHECK ( idx.hasProvision (_entry (7,"cat"))); + CHECK ( idx.hasProvision (_entry (4,"dog"))); + CHECK (_hasSolution (1,7)); // because cat-7 is newly added, it shadows the older cat-9 + CHECK (_hasSolution (5,7)); + CHECK (_hasSolution (6,7)); + CHECK (_hasSolution (3,4)); // but dog remains dog + + CHECK (p_cnt+2 == idx.provision_count()); + CHECK (r_cnt == idx.request_count()); + CHECK (idx.isValid()); + } + + + void + clearIndex (Index& idx) + { + idx.clear(); + CHECK (idx.isValid()); + CHECK (0 == idx.size()); + } + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceIndex_test, "function common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/advice/advice-multiplicity-test.cpp b/tests/lib/advice/advice-multiplicity-test.cpp new file mode 100644 index 000000000..35cf42e5b --- /dev/null +++ b/tests/lib/advice/advice-multiplicity-test.cpp @@ -0,0 +1,134 @@ +/* + AdviceMultiplicity(Test) - verify correctness when dispatching multiple Advices concurrently + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +//#include "lib/test/test-helper.hpp" + +#include "lib/advice.hpp" +//#include "lib/p.hpp" +//#include "proc/assetmanager.hpp" +//#include "proc/asset/inventory.hpp" +//#include "proc/mobject/session/clip.hpp" +//#include "proc/mobject/session/track.hpp" +//#include "lib/meta/trait-special.hpp" +//#include "lib/util-foreach.hpp" +//#include "lib/symbol.hpp" + +//#include +//#include + +//using lib::test::showSizeof; +//using lib::test::randStr; +//using util::isSameObject; +//using util::and_all; +//using util::for_each; +//using util::isnil; +//using lib::Literal; +//using lib::Symbol; +//using lumiera::P; +//using std::string; +//using std::cout; +//using std::endl; + + + +namespace lib { +namespace advice { +namespace test { + + namespace { + } + + + + /******************************************************************************* + * @test stress test for the Advice system: + * Concurrently add a multitude of advice provisions and check correct + * matching and dispatch of all advice. + * + * @todo advanced topic, deferred for now (4/10) ////////////////////TICKET #610 + * + * @see advice.hpp + * @see AdviceBasics_test + */ + class AdviceMultiplicity_test : public Test + { + + virtual void + run (Arg) + { + check_highLoadSimpleMatch(); + check_multipleMatch(); + check_unlockedDispatch(); + } + + + /** @test run simple pairs of collaborators in multiple threads. + * Intentionally, there should be just a single match per pair, + * but the timings of provision and pickup are chosen randomly + */ + void + check_highLoadSimpleMatch() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 + } + + + /** @test here, one advice might reach multiple advised entities and + * one entity may receive multiple pieces of advice, overwriting + * previous advice provisions. The receiving clients (advised entities) + * are polling irregularly, but finally should each pick up the correct + * value. To check this, advice values are generated with a specific + * pattern, which can be check summed */ + void + check_multipleMatch() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 + } + + + /** @test when dispatching Advice, some of the locking can be left out. + * Obviously this means we can't be sure anymore the client will + * see the newly dispatched piece of advice. But the main focus + * of this test is to ensure the advice system itself is working + * properly even without complete locking. + * To verify the results, each thread performs a kind of "flush" + * (actually creates a memory barrier) before picking up the + * final value */ + void + check_unlockedDispatch() + { +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #610 + } + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceMultiplicity_test, "function common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/advice/advice-situations-test.cpp b/tests/lib/advice/advice-situations-test.cpp new file mode 100644 index 000000000..35110156a --- /dev/null +++ b/tests/lib/advice/advice-situations-test.cpp @@ -0,0 +1,115 @@ +/* + AdviceSituations(Test) - catalogue of standard Advice usage scenarios + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +//#include "lib/test/test-helper.hpp" + +#include "lib/advice.hpp" +//#include "lib/p.hpp" +//#include "proc/assetmanager.hpp" +//#include "proc/asset/inventory.hpp" +//#include "proc/mobject/session/clip.hpp" +//#include "proc/mobject/session/track.hpp" +//#include "lib/meta/trait-special.hpp" +//#include "lib/util-foreach.hpp" +//#include "lib/symbol.hpp" + +//#include +//#include + +//using lib::test::showSizeof; +//using lib::test::randStr; +//using util::isSameObject; +//using util::and_all; +//using util::for_each; +//using util::isnil; +//using lib::Literal; +//using lib::Symbol; +//using lumiera::P; +//using std::string; +//using std::cout; +//using std::endl; + + + +namespace lib { +namespace advice { +namespace test { + + namespace { + } + + + + /****************************************************************************************** + * @test documentation of the fundamental usage scenarios envisioned in the Advice concept. + * This test will be augmented and completed as the Lumiera application matures. + * + * @todo partially unimplemented and thus commented out ////////////////////TICKET #335 + * + * @see advice.hpp + * @see AdviceBasics_test + * @see AdviceConfiguration_test + */ + class AdviceSituations_test : public Test + { + + virtual void + run (Arg) + { + check_ProxyRenderingAdvice(); + check_DependencyInjection(); + TODO ("more advice usage scenarios.....?"); + } + + + /** @test usage scenario: switch a processing node into proxy mode. */ + void + check_ProxyRenderingAdvice() + { + UNIMPLEMENTED ("anything regarding proxy rendering"); +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #335 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #335 + } + + + /** @test usage scenario: dependency injection for tests */ + void + check_DependencyInjection() + { + UNIMPLEMENTED ("suitable advice to request and transfer test dependencies"); +#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #335 +#endif /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #335 + } + + // more to come..... + + }; + + + + /** Register this test class... */ + LAUNCHER (AdviceSituations_test, "function common"); + + +}}} // namespace lib::advice::test diff --git a/tests/lib/del-stash-test.cpp b/tests/lib/del-stash-test.cpp new file mode 100644 index 000000000..f09500b98 --- /dev/null +++ b/tests/lib/del-stash-test.cpp @@ -0,0 +1,265 @@ +/* + DelStash(Test) - verify a facility to memorise and trigger deleter functions + + Copyright (C) Lumiera.org + 2010, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/del-stash.hpp" + +#include + + + +namespace lib { +namespace test{ + + using std::rand; + + + + namespace { // probe victims + + ulong MAX_MASS = 200; // number of victims to kill at once + + ulong checksum = 0; + + + template + class Probe + { + uint mySiz_; + char myCrap_[siz]; + + public: + Probe() + : mySiz_(siz) + { + REQUIRE (siz); + for (uint i=0; i + inline Probe* + makeViktim () + { + return new Probe(); + } + + template + inline void + feedViktim (DelStash& killer) + { + killer.manage (new Probe()); + } + + + }//(End) test data + + + + + /**************************************************************************** + * @test create a bunch of objects with varying type and size, memorising + * how to kill them properly. Verify everyone is dead after mass-kill. + * Use a checksum not only to verify the number of objects created and + * destroyed, but also the individual (random) contents of the data + * within the objects, to ensure that the correct destructor + * actually is invoked for each type. + * + * @see lib::DelStash + */ + class DelStash_test : public Test + { + + virtual void + run (Arg) + { + checksum = 0; + checkSingleKill(); + checkCustomKill(); + checkMassKill(); + checkAutoKill(); + } + + + void + checkSingleKill () + { + DelStash killer; + CHECK (0 == killer.size()); + + killer.manage (NULL); + CHECK (0 == killer.size()); + + Probe<5> *p = makeViktim<5>(); + Probe<7> &r = *makeViktim<7>(); + void *v = makeViktim<9>(); + CHECK (0 < checksum); + + killer.manage (p); + killer.manage (r); + killer.manage > (v); + + CHECK (3 == killer.size()); + + killer.kill (r); + CHECK (2 == killer.size()); + + killer.kill (p); + CHECK (1 == killer.size()); + + killer.kill (p); + CHECK (1 == killer.size()); // spurious kill requests ignored + + killer.kill (v); + CHECK (0 == killer.size()); + CHECK (0 == checksum); + } + + + void + feedViktims (DelStash& killer) + { + for (uint i=1; i <= MAX_MASS; ++i) + switch (i% 5) { + case 0: feedViktim<12> (killer); break; + case 1: feedViktim<23> (killer); break; + case 2: feedViktim<34> (killer); break; + case 3: feedViktim<45> (killer); break; + case 4: feedViktim<56> (killer); break; + } + } + + + void + checkMassKill () + { + DelStash killer; + CHECK (0 == killer.size()); + + CHECK (0 == checksum); + CHECK (0 == killer.size()); + + feedViktims (killer); + CHECK (MAX_MASS == killer.size()); + + killer.killAll(); + CHECK (0 == killer.size()); + CHECK (0 == checksum); + } + + + void + checkAutoKill() + { + { + DelStash killer; + CHECK (0 == killer.size()); + CHECK (0 == checksum); + + feedViktims (killer); + Probe<444> * individuum = makeViktim<444>(); + killer.manage (individuum); + feedViktims (killer); + killer.manage (makeViktim<5555>()); + feedViktims (killer); + + CHECK (3*MAX_MASS + 2 == killer.size()); + + killer.kill(individuum); + CHECK (3*MAX_MASS + 1 == killer.size()); + + CHECK (0 < checksum); + }// killer going out of scope... + + CHECK (0 == checksum); + } + + + /** @test use a custom-provided + * deleter function + */ + void + checkCustomKill () + { + DelStash killer; + CHECK (0 == killer.size()); + + /** a very specific setup, + * bound to mess up the checksum, + * unless the random bias is removed + * by the custom deleter function + */ + class Special + : Probe<555> + { + char secret_; + + public: + Special() + : Probe<555>() + , secret_('a' + (rand() % (1+'z'-'a'))) + { + checksum += secret_; + } + + static void + selfKill (void *it) + { + Special *self = static_cast (it); + checksum -= self->secret_; + delete self; + } + }; + + + void * type_erased = new Special(); + CHECK (0 < checksum); + + killer.manage (type_erased, &Special::selfKill); + CHECK (1 == killer.size()); + + killer.kill(type_erased); + CHECK (0 == killer.size()); + CHECK (0 == checksum); + } + }; + + + /** Register this test class... */ + LAUNCHER (DelStash_test, "unit common"); + + +}} // namespace lib::test diff --git a/tests/lib/query/query-utils-test.cpp b/tests/lib/query/query-utils-test.cpp new file mode 100644 index 000000000..b631d6f8a --- /dev/null +++ b/tests/lib/query/query-utils-test.cpp @@ -0,0 +1,169 @@ +/* + QueryUtils(Test) - checking various utils provided for dealing with config queries + + Copyright (C) Lumiera.org + 2008, Hermann Vosseler + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +#include "lib/util.hpp" +#include "lib/util-foreach.hpp" + +#include "lib/cmdline.hpp" +#include "lib/query.hpp" +#include "query/querydiagnostics.hpp" + +#include +#include + +using lumiera::Query; +using util::Cmdline; +using util::isnil; +using util::contains; +using util::for_each; + +using std::tr1::placeholders::_1; +using std::tr1::bind; +using std::string; +using std::cout; +using std::endl; + + + +namespace lumiera { +namespace query { +namespace test{ + + + struct Thing + { + virtual ~Thing() {} // add RTTI for Query.asKey(); + }; + + + + /************************************************************************ + * @test check the various small helpers and utilities we utilise + * for dealing with ConfigQuery + */ + class QueryUtils_test : public Test + { + + virtual void + run (Arg arg) + { + if (isnil(arg)) arg = Cmdline ("Query normaliseID extractID removeTerm countPred"); + + if (contains (arg, "Query" )) check_Query (); + if (contains (arg, "normaliseID")) check_normaliseID(); + if (contains (arg, "extractID" )) check_extractID (); + if (contains (arg, "removeTerm" )) check_removeTerm (); + if (contains (arg, "countPred" )) check_countPred (); + } + + + + /** @test Query wrapper class basics */ + void + check_Query () + { + cout << Query ("I am writing a test sentence.").asKey() << endl; + } + + + + /** @test sanitising and normalising various tokens */ + void + check_normaliseID () + { + Cmdline tokens ("a A AA dufte 1a _1 A_A BÄH"); + tokens.push_back (""); + tokens.push_back (" White \t space "); + tokens.push_back ("§&Ω%€GΩ%€ar ☠☠☠ baäääääge!!!!! "); + + cout << "..original : " << tokens << " :"< - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -* *****************************************************/ - - -#include "lib/test/run.hpp" -#include "lib/util.hpp" -#include "lib/util-foreach.hpp" - -#include "lib/cmdline.hpp" -#include "lib/query.hpp" -#include "query/querydiagnostics.hpp" - -#include -#include - -using lumiera::Query; -using util::Cmdline; -using util::isnil; -using util::contains; -using util::for_each; - -using std::tr1::placeholders::_1; -using std::tr1::bind; -using std::string; -using std::cout; - - - -namespace lumiera { - namespace query { - namespace test{ - - - struct Thing - { - virtual ~Thing() {} // add RTTI for Query.asKey(); - }; - - - - /************************************************************************ - * @test check the various small helpers and utilities we utilise - * for dealing with ConfigQuery - */ - class QueryUtils_test : public Test - { - - virtual void - run (Arg arg) - { - if (isnil(arg)) arg = Cmdline ("Query normaliseID extractID removeTerm countPraed"); - - if (contains (arg, "Query" )) check_Query (); - if (contains (arg, "normaliseID")) check_normaliseID (); - if (contains (arg, "extractID" )) check_extractID (); - if (contains (arg, "removeTerm" )) check_removeTerm (); - if (contains (arg, "countPraed" )) check_countPraed (); - } - - - - /** @test Query wrapper class basics */ - void - check_Query () - { - cout << Query ("I am writing a test sentence.").asKey() << "\n"; - } - - - - /** @test sanitising and normalising various tokens */ - void - check_normaliseID () - { - Cmdline tokens ("a A AA dufte 1a _1 A_A BÄH"); - tokens.push_back (""); - tokens.push_back (" White \t space "); - tokens.push_back ("§&Ω%€GΩ%€ar Ω baäääääge!!!!! "); - - cout << "..original : " << tokens << " :\n"; - - for_each (tokens, bind ( &normaliseID, _1 )); - - cout << "normalised : " << tokens << " :\n"; - } - - - - /** @test the simple regexp extracting a parameter token */ - void - check_extractID () - { - ASSERT ("tok" == extractID ("pred", "pred(tok)." )); - ASSERT ("tok" == extractID ("pred", " pred( tok )" )); - ASSERT ("tok" == extractID ("pred", "pred(tok), pred(tux)." )); - ASSERT ("tok" == extractID ("pred", "other(xyz) pred(tok) pred(tux)" )); - ASSERT ("tok" == extractID ("pred", "some( pred(tok)" )); - - ASSERT (isnil (extractID ("pred", "pred (tok)"))); - ASSERT (isnil (extractID ("pred", "pred tok)" ))); - ASSERT (isnil (extractID ("pred", "pred(tok " ))); - } - - - - /** @test the regexp based cutting of a term with given symbol */ - void - check_removeTerm () - { - // successful------Symbol---input-string----------------------extracted------remaining------------- - ASSERT_removeTerm ("pred", "pred(tok).", "pred(tok)", "." ); - ASSERT_removeTerm ("pred", " pred( tok )", "pred(tok)", " " ); - ASSERT_removeTerm ("pred", "pred(tok), pred(tux).", "pred(tok)", "pred(tux)." ); - ASSERT_removeTerm ("pred", "other(xyz) pred(tok) pred(tux)", "pred(tok)", "other(xyz) pred(tux)" ); - ASSERT_removeTerm ("pred", "some( pred(tok)", "pred(tok)", "some( " ); - - // not successful - ASSERT_removeTerm ("pred", "pred (tok", "", "pred (tok" ); - ASSERT_removeTerm ("pred", "pred tok)", "", "pred tok)" ); - ASSERT_removeTerm ("pred", "pred(tok", "", "pred(tok" ); - } - - void - ASSERT_removeTerm (Symbol sym, string input, string extracted, string modified) - { - ASSERT (extracted == removeTerm (sym, input)); - ASSERT (modified == input); - } - - - - /** @test counting of predicates in a query - * (currently 4/08 regexp based...) - */ - void - check_countPraed () - { - for (uint i=1; i <= 30; ++i) - ASSERT ( i == countPraed (garbage_query (i))); - } - }; - - - /** Register this test class... */ - LAUNCHER (QueryUtils_test, "unit query"); - - - - } // namespace test - - } // namespace query - -} // namespace lumiera diff --git a/uml/lumiera/128517 b/uml/lumiera/128517 index 057be77a3..d87549fd1 100644 --- a/uml/lumiera/128517 +++ b/uml/lumiera/128517 @@ -1,6 +1,6 @@ format 58 "CommonLib" // CommonLib - revision 16 + revision 19 modified_by 5 "hiv" // class settings //class diagram settings @@ -215,6 +215,467 @@ ${inlines} end end + classview 134533 "Advice" + //class diagram settings + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + //collaboration diagram settings + show_full_operations_definition default show_hierarchical_rank default write_horizontally default drawing_language default package_name_in_tab default show_context default draw_all_relations default shadow default show_stereotype_properties default + //object diagram settings + write_horizontally default package_name_in_tab default show_context default auto_label_position default draw_all_relations default shadow default show_stereotype_properties default + //sequence diagram settings + show_full_operations_definition default write_horizontally default class_drawing_mode default drawing_language default draw_all_relations default shadow default show_stereotype_properties default + //state diagram settings + package_name_in_tab default show_context default auto_label_position default write_trans_label_horizontally default show_trans_definition default draw_all_relations default shadow default + show_activities default region_horizontally default drawing_language default show_stereotype_properties default + //class settings + //activity diagram settings + package_name_in_tab default show_context default show_opaque_action_definition default auto_label_position default write_flow_label_horizontally default draw_all_relations default shadow default + show_infonote default drawing_language default show_stereotype_properties default + classdiagram 141445 "Advice entities" + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + size A4 + end + + class 163973 "Advice" + visibility package stereotype "entity" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "${comment}${@}${visibility}${final}${abstract}class ${name}${extends}${implements} { +${members}} +" + php_decl "${comment}${final}${visibility}${abstract}class ${name}${extends}${implements} { +${members}} +" + python_2_2 python_decl "class ${name}${inherit}: +${docstring}${members} +" + idl_decl "${comment}${abstract}${custom}valuetype ${name}${inherit} { +${members}}; +" + explicit_switch_type "" + + end + + class 164101 "PointOfAdvice" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + end + + class 164229 "Advisor" + visibility package stereotype "actor" + cpp_decl "" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 199045 // + relation 188549 ---> + stereotype "add" + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 199045 // + b parent class_ref 164613 // Provision + end + end + + class 164357 "Advised" + visibility package stereotype "actor" + cpp_decl "" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 198917 // + relation 188421 ---> + stereotype "owns" + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 198917 // + b parent class_ref 164485 // Request + end + end + + class 165893 "AdviceLink" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 201093 // + relation 190213 ---|> + a public + cpp default "${type}" + classrelation_ref 201093 // + b parent class_ref 164101 // PointOfAdvice + end + + classrelation 201733 // + relation 190853 ---> + stereotype "attach" + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 201733 // + b parent class_ref 166149 // AdviceSystem + end + end + + class 164485 "Request" + visibility package + nformals 1 + formal name "AD" type "class" explicit_default_value "" + explicit_extends "" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 199685 // + relation 188933 ---- + a role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 199685 // + b role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 199813 // + end + + classrelation 201349 // + relation 190469 ---|> + a public + cpp default "${type}" + classrelation_ref 201349 // + b parent class_ref 165893 // AdviceLink + end + + operation 143749 "getAdvice" + public explicit_return_type "" + nparams 0 + cpp_decl " ${comment}${friend}${static}${inline}${virtual}${type} ${name} ${(}${)}${const}${volatile} ${throw}${abstract};" + cpp_def "${comment}${inline}${type} +${class}::${name} ${(}${)}${const}${volatile} ${throw}${staticnl} +{ + ${body} +} + +" + + + + + end + end + + class 164613 "Provision" + visibility package + nformals 1 + formal name "AD" type "class" explicit_default_value "" + explicit_extends "" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 199173 // + relation 188677 ---- + a role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 199173 // + b role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 199301 // + end + + classrelation 201221 // + relation 190341 ---|> + a public + cpp default "${type}" + classrelation_ref 201221 // + b parent class_ref 165893 // AdviceLink + end + + operation 143621 "setAdvice" + public explicit_return_type "" + nparams 0 + cpp_decl " ${comment}${friend}${static}${inline}${virtual}${type} ${name} ${(}${)}${const}${volatile} ${throw}${abstract};" + cpp_def "${comment}${inline}${type} +${class}::${name} ${(}${)}${const}${volatile} ${throw}${staticnl} +{ + ${body} +} + +" + + + + + end + + classrelation 203141 // + relation 192261 -_-> + stereotype "create" + a package + cpp default "#include in source" + classrelation_ref 203141 // + b parent class_ref 166021 // ActiveProvision + end + end + + class 166021 "ActiveProvision" + visibility package + nformals 1 + formal name "AD" type "class" explicit_default_value "" + explicit_extends "" + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 201477 // + relation 190597 ---> + stereotype "holds" + a role_name "" multiplicity "1" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 201477 // + b multiplicity "1" parent class_ref 163973 // Advice + end + + classrelation 201605 // + relation 190725 ---|> + a public + cpp default "${type}" + classrelation_ref 201605 // + b parent class_ref 164101 // PointOfAdvice + end + end + + class 164741 "Binding" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 199301 // + relation_ref 188677 // + end + + classrelation 199813 // + relation_ref 188933 // + end + end + + class 166149 "AdviceSystem" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 201989 // + relation 191109 ---> + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type}* ${name}${value}; +" + classrelation_ref 201989 // + b parent class_ref 166277 // Index + end + end + + class 166277 "Index" + visibility package + cpp_decl "${comment}${template}class ${name}${inherit} + { +${members} }; +${inlines} +" + java_decl "" + php_decl "" + python_2_2 python_decl "" + idl_decl "" + explicit_switch_type "" + + classrelation 201861 // + relation 190981 *--> + a role_name "" protected + cpp default " ${comment}${static}${mutable}${volatile}${const}${type} ${name}${value}; +" + classrelation_ref 201861 // + b parent class_ref 164741 // Binding + end + end + + objectdiagram 141573 "Advice solving" + write_horizontally default package_name_in_tab default show_context default auto_label_position default draw_all_relations default shadow default show_stereotype_properties default + size A4 + end + + classinstance 142981 "" + type class_ref 164613 // Provision + attributes + end + relations + end + end + + classinstance 143109 "" + type class_ref 164613 // Provision + attributes + end + relations + end + end + + classinstance 143237 "" + type class_ref 164613 // Provision + attributes + end + relations + end + end + + classinstance 143365 "" + type class_ref 164229 // Advisor + attributes + end + relations + end + end + + classinstance 143493 "" + type class_ref 164357 // Advised + attributes + end + relations + end + end + + classinstance 143621 "" + type class_ref 164485 // Request + attributes + end + relations + end + end + + classinstance 143749 "" + type class_ref 164357 // Advised + attributes + end + relations + end + end + + classinstance 143877 "" + type class_ref 164485 // Request + attributes + end + relations + end + end + + classinstance 144005 "" + type class_ref 164741 // Binding + attributes + end + relations + end + end + + classinstance 144133 "" + type class_ref 164741 // Binding + attributes + end + relations + end + end + + classinstance 144261 "" + type class_ref 164741 // Binding + attributes + end + relations + end + end + + classinstance 144389 "" + type class_ref 164741 // Binding + attributes + end + relations + end + end + + classinstance 144517 "" + type class_ref 164741 // Binding + attributes + end + relations + end + end + end + classview 129285 "StreamType" //class diagram settings draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default diff --git a/uml/lumiera/141445.diagram b/uml/lumiera/141445.diagram new file mode 100644 index 000000000..61830e5ae --- /dev/null +++ b/uml/lumiera/141445.diagram @@ -0,0 +1,128 @@ +format 58 + +classcanvas 128005 class_ref 163973 // Advice + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + color lightmagenta + xyz 67 17 2000 +end +classcanvas 128133 class_ref 164101 // PointOfAdvice + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 266 11 2000 +end +classcanvas 128389 class_ref 164229 // Advisor + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 19 202 2000 +end +classcanvas 128517 class_ref 164357 // Advised + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 551 202 2000 +end +classcanvas 128645 class_ref 164485 // Request + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 435 207 2000 +end +classcanvas 129157 class_ref 164613 // Provision + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 174 207 2000 +end +classcanvas 129285 class_ref 164741 // Binding + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 283 219 2000 +end +classcanvas 130437 class_ref 165893 // AdviceLink + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 274 90 2005 +end +classcanvas 131461 class_ref 166021 // ActiveProvision + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 157 90 2000 +end +classcanvas 132101 class_ref 166149 // AdviceSystem + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 405 90 2000 +end +classcanvas 132229 class_ref 166277 // Index + draw_all_relations default hide_attributes default hide_operations default show_members_full_definition default show_members_visibility default show_members_stereotype default show_members_multiplicity default show_members_initialization default member_max_width 0 show_parameter_dir default show_parameter_name default package_name_in_tab default class_drawing_mode default drawing_language default show_context_mode default auto_label_position default show_infonote default shadow default show_stereotype_properties default + xyz 363 128 2000 +end +relationcanvas 129413 relation_ref 188421 // + from ref 128517 z 1999 stereotype "<>" xyz 510 223 3000 to ref 128645 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 129541 relation_ref 188549 // + from ref 128389 z 1999 stereotype "<>" xyz 72 223 3000 to ref 129157 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 129669 relation_ref 188677 // + from ref 129157 z 1999 to ref 129285 + no_role_a no_role_b + multiplicity_a_pos 266 244 3000 multiplicity_b_pos 246 244 3000 +end +relationcanvas 129925 relation_ref 188933 // + from ref 128645 z 1999 to ref 129285 + no_role_a no_role_b + multiplicity_a_pos 333 240 3000 multiplicity_b_pos 427 241 3000 +end +relationcanvas 130565 relation_ref 190213 // + from ref 130437 z 1999 to ref 128133 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 130693 relation_ref 190341 // + geometry VHV unfixed + from ref 129157 z 1999 to point 203 184 + line 131205 z 1999 to point 305 184 + line 131333 z 1999 to ref 130437 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 130821 relation_ref 190469 // + geometry VHV unfixed + from ref 128645 z 1999 to point 465 184 + line 130949 z 1999 to point 305 184 + line 131077 z 1999 to ref 130437 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 131589 relation_ref 190597 // + from ref 131461 z 1999 stereotype "<>" xyz 101 79 3000 to ref 128005 + no_role_a no_role_b + multiplicity_a_pos 114 65 3000 multiplicity_b_pos 147 92 3000 +end +relationcanvas 131717 relation_ref 190725 // + geometry VHV + from ref 131461 z 1999 to point 200 67 + line 131845 z 1999 to point 305 67 + line 131973 z 1999 to ref 128133 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 132613 relation_ref 190853 // + from ref 130437 z 1999 stereotype "<>" xyz 343 96 3000 to ref 132101 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 132741 relation_ref 190981 // + from ref 132229 z 1999 to point 383 199 + line 132997 z 1999 to ref 129285 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 133125 relation_ref 191109 // + geometry HVr + from ref 132101 z 1999 to point 444 145 + line 133253 z 1999 to ref 132229 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +relationcanvas 133381 relation_ref 192261 // + decenter_end 98 + from ref 129157 z 1999 stereotype "<>" xyz 109 149 3000 to point 163 194 + line 133765 z 1999 to ref 131461 + no_role_a no_role_b + no_multiplicity_a no_multiplicity_b +end +preferred_whz 635 331 1 +end diff --git a/uml/lumiera/141573.diagram b/uml/lumiera/141573.diagram new file mode 100644 index 000000000..2def53e54 --- /dev/null +++ b/uml/lumiera/141573.diagram @@ -0,0 +1,75 @@ +format 58 + +classinstancecanvas 128005 classinstance_ref 142981 // + xyz 149 66 2000 +end +classinstancecanvas 128133 classinstance_ref 143109 // + xyz 149 101 2000 +end +classinstancecanvas 128261 classinstance_ref 143237 // + xyz 149 135 2000 +end +classinstancecanvas 128389 classinstance_ref 143365 // + xyz 7 62 2005 color blue +end +classinstancecanvas 128645 classinstance_ref 143237 // + xyz 7 135 2000 +end +classinstancecanvas 128773 classinstance_ref 143493 // + xyz 482 164 2000 color blue +end +classinstancecanvas 128901 classinstance_ref 143621 // + xyz 388 164 2005 +end +classinstancecanvas 129029 classinstance_ref 143749 // + xyz 482 108 2000 color blue +end +classinstancecanvas 129157 classinstance_ref 143877 // + xyz 388 108 2010 +end +classinstancecanvas 129285 classinstance_ref 144005 // + xyz 311 281 2000 +end +classinstancecanvas 129413 classinstance_ref 144133 // + xyz 311 308 2000 +end +classinstancecanvas 129541 classinstance_ref 144261 // + xyz 226 254 2000 +end +classinstancecanvas 129669 classinstance_ref 144389 // + xyz 226 281 2000 +end +classinstancecanvas 129797 classinstance_ref 144517 // + xyz 226 308 2000 +end +textcanvas 131205 "match" + xyzwh 280 318 2005 29 13 +fragment 131333 "Binding index" + color green xyzwh 206 229 1994 164 113 +end +note 131461 "Advice +Solution" + color green fg darkgreen xyzwh 285 145 2004 63 44 +fragment 131589 "Advice system" + color lightgreen xyzwh 135 18 1989 245 334 +end +objectlinkcanvas 131077 norel + from ref 129797 z 1999 to ref 129413 + no_role_a no_role_b +objectlinkcanvas 131973 norel + from ref 128901 z 1999 to ref 128261 + no_role_a no_role_b +line 130053 -_-_ + from ref 128389 z 1999 to ref 128645 +line 130181 -_-_ + from ref 128645 z 1999 to ref 128261 +line 130309 -_-_ + from ref 128773 z 1999 to ref 128901 +line 130437 -_-_ geometry HVr + from ref 128901 z 1999 to point 428 316 + line 130565 z 1999 to ref 129413 +line 130693 -_-_ geometry VH + from ref 128261 z 1999 to point 191 316 + line 130949 z 1999 to ref 129797 +preferred_whz 556 483 1 +end diff --git a/uml/lumiera/5.session b/uml/lumiera/5.session index b86df7d15..293f4231c 100644 --- a/uml/lumiera/5.session +++ b/uml/lumiera/5.session @@ -6,8 +6,12 @@ diagrams 730 488 100 4 0 0 classdiagram_ref 139141 // Meta-Asset Relations 469 451 100 4 0 0 - active classdiagram_ref 140293 // TypedLookup + classdiagram_ref 140293 // TypedLookup 721 697 100 4 0 0 + active classdiagram_ref 141445 // Advice entities + 635 331 100 4 0 0 + objectdiagram_ref 141573 // Advice solving + 556 483 100 4 0 0 end show_stereotypes selected @@ -33,7 +37,12 @@ open classview_ref 128261 // Builder Workings usecaseview_ref 128261 // config examples class_ref 133253 // Frame - classview_ref 129285 // StreamType + class_ref 164485 // Request + class_ref 164613 // Provision + class_ref 166021 // ActiveProvision + class_ref 164741 // Binding + class_ref 166277 // Index + class_ref 145285 // MediaKind package_ref 131077 // ConfigQuery class_ref 152965 // Handle diff --git a/uml/lumiera/lumiera.prj b/uml/lumiera/lumiera.prj index 1b9206c7a..f3b36633d 100644 --- a/uml/lumiera/lumiera.prj +++ b/uml/lumiera/lumiera.prj @@ -1,6 +1,6 @@ format 58 "lumiera" - revision 61 + revision 63 modified_by 5 "hiv" cpp_root_dir "../../src/" diff --git a/wiki/draw/AdviceBindingIndex1.png b/wiki/draw/AdviceBindingIndex1.png new file mode 100644 index 000000000..87c527744 Binary files /dev/null and b/wiki/draw/AdviceBindingIndex1.png differ diff --git a/wiki/renderengine.html b/wiki/renderengine.html index 5997704c9..be2a9b466 100644 --- a/wiki/renderengine.html +++ b/wiki/renderengine.html @@ -514,12 +514,15 @@ ColorPalette SiteUrl -
-
{{red{WIP 11/09}}}...//about to explicate a pattern which I'm aiming at within the design almost since the beginning//
+

+
//pattern of collaboration for loosely coupled entities, to be used for various purposes within Proc...//
 Expecting Advice and giving Advice &mdash; this collaboration ranges somewhere between messaging and dynamic properties, but cross-cutting the primary, often hierarchical relation of dependencies. Always happening at a certain //point of advice,// which creates a distinct, static nature different of being just a convention, on the other hand, Advice is deliberately kept optional and received synchronously, albeit possibly within an continuation.
 
 !Specification
-''Definition'': Advice is an optional, mediated collaboration between entities taking on the roles of advisor and advised, thereby passing a custom piece of advice data, managed by the advice support system. The possibility of advice is created by the advised entity by exposing a point of advice, while the advising entity can discover this advice possibility.
+''Definition'': Advice is an optional, mediated collaboration between entities taking on the roles of advisor and advised, thereby passing a custom piece of advice data, managed by the advice support system. The possibility of advice is created by both of the collaborators entering the system, where the advised entity exposes a point of advice, while the advising entity provides an actual advice value.
+[>img[Entities for Advice collaboration|uml/fig141445.png]]
+
+
 !!Collaborators
 * the ''advised'' entity 
 * the ''advisor''
@@ -527,10 +530,207 @@ Expecting Advice and giving Advice &mdash; this collaboration ranges somewhe
 * ''advice system''
 * the ''binding''
 * the ''advice''
-The ''advised'' entity opens the collaboration by requsting an advice. The ''advice'' itself is a piece of data of a custom type, which needs to be //copyable.// Obviously, both the advised and the advisor need to share knowledge about the meaning of this advice data. (in a more elaborate version we might allow the advisor to provide a subclass of the advice interface type). The actual advice colaboration happens at a ''point of advice'', which needs to be derived first. To this end, the adviced puts up an request by providing his ''binding'', which is a pattern for matching. An entity willing to give advice //discovers//&nbsp possible ''advice channels'' by putting up an advisor binding, which similarily is a pattern. The ''advice system'' as mediator resolves both sides, by matching (which in the most general case could be an unification). This process creates an ''advice point solution'' &mdash; and in the most general case even multiple solutions. If we allow such, there needs to be a scheme for both sides to handle this (unexpected) multiplicity of advice points. Anyway, now the actual colaboration takes place by the advisor placing the piece of advice into the advice channel, causing it to be placed into the point of advice. After passing a certain (implementation defined) break point, the advice leaves the influence of the advisor and gets exposed to the advised entitie(s). Typically this involves copying the advice data into a location managed by the advice system. In the most simple case, the advised entity accesses the advice synchronously (an non-blocking). Of course, there could be a status flag to find out if there is new advice. Moreover, typically the advice data type is default constructible and thus there is always a basic form of advice available, thereby completely decoupling the advised entity from the timings related to this colaboration.
+Usually, the ''advised'' entity opens the collaboration by requesting an advice. The ''advice'' itself is a piece of data of a custom type, which needs to be //copyable.// Obviously, both the advised and the advisor need to share knowledge about the meaning of this advice data. (in a more elaborate version we might allow the advisor to provide a subclass of the advice interface type). The actual advice collaboration happens at a ''point of advice'', which needs to be derived first. To this end, two prerequisites are to be fulfilled (without fixed sequence): The advised puts up an ''advice request'' by specifying his ''binding'', which is a pattern for matching. An entity about to give advice attaches a possible ''advice provision'', combined with an advisor binding, which similarly is a pattern. The ''advice system'' as mediator resolves both sides, by matching (which in the most general case could be an unification). This process creates an ''advice point solution'' &mdash; allowing the advisor to fed the piece of advice into a kind of communication channel (&raquo;advice channel&laquo;), causing the advice data to be placed into the point of advice. After passing a certain (implementation defined) break point, the advice leaves the influence of the advisor and gets exposed to the advised entities. Especially, this involves copying the advice data into a location managed by the advice system. In the standard case, the advised entity picks up the advice synchronously (and non-blocking). Of course, there could be a status flag to find out if there is new advice. Moreover, typically the advice data type is default constructible and thus there is always a basic form of advice available, thereby completely decoupling the advised entity from the timings related to this collaboration.
 
 !!extensions
-In a more elaborate scheme, the advised entiy could provide a signal to be invoked either in the thread context of the advisor (being still blocked in the advice providing call), or in a completely separate thread. A third solution would be to allow the advised entity to block until recieving new advice. Both of these more elaborate schemes would also allow to create an advice queue. 
+In a more elaborate scheme, the advised entity could provide a signal to be invoked either in the thread context of the advisor (being still blocked in the advice providing call), or in a completely separate thread. A third solution would be to allow the advised entity to block until receiving new advice. Both of these more elaborate schemes would also allow to create an advice queue &mdash; thereby developing the advice collaboration into a kind of messaging system. Following this route seems questionable though.
+
+&rarr; AdviceSituations
+&rarr; AdviceRequirements
+&rarr; AdviceImplementation
+

+

+

+
[<img[Advice solution|uml/fig141573.png]]
+
+
+
+
+
+The advice system is //templated on the advice type// &mdash; so basically any collaboration is limited to a distinct advice type. But currently (as of 5/2010), this typed context is kept on the interface level, while the implementation is built on top of a single lookup table (which might create contention problems in the future and thus may be changed without further notice). The advice system is a system wide singleton service, but it is never addressed directly by the participants. Rather, instances of ~AdviceProvision and ~AdviceRequest act as point of access. But these aren't completely symmetric; while the ~AdviceRequest is owned by the advised entity, the ~AdviceProvision is a value object, a uniform holder used to introduce new advice into the system. ~AdviceProvision is copied into an internal buffer and managed by the advice system, as is the actual advice item, which is copied alongside.
+
+In order to find matches and provide advice solutions, the advice system maintains an index data structure called ''~Binding-Index''. The actual binding predicates are represented by value objects stored within this index table. The matching process is triggered whenever a new possibility for an advice solution enters the system, which could be a new request, a new provision or a change in the specified bindings. A successful match causes a pointer to be set within the ~AdviceRequest, pointing to the ~AdviceProvision acting as solution. Thus, when a solution exists, the advised entity can access the advice value object by dereferencing this pointer. A new advice solution just results in setting a different pointer, which is atomic and doesn't need to be protected by locking. But note, omitting the locking means there is no memory barrier; thus the advised entity might not see any changed advice solution, until the corresponding thread(s) refresh their CPU cache. This might or might not be acceptable, depending on the context, and thus is configurable as policy. Similarly, the handling of default advice is configurable. Usually, advice is a default constructible value object. In this case, when there isn't any advice solution (yet), a pseudo solution holding the default constructed advice value is used to satisfy any advice access by the client (advised entity). The same can be used when the actual ~AdviceProvision gets //retracted.// As an alternative, when this default solution approach doesn't work, we can provide a policy either to throw or to wait blocking &mdash; but this alternative policy is similarly implemented with an //null object// (a placeholder ~AdviceProvision). Anyway, this implementation technique causes the advice system to collect some advice provisions, bindings and advice objects over time. It should use a pooling custom allocator in the final version. As the number of advisors is expected to be rather small, the storage occupied by these elements, which is effectively blocked until application exit, isn't considered a problem.
+
+!organising the advice solution
+This is the tricky part of the whole advice system implementation. A naive implementation will quickly degenerate in performance, as costs are of order ~AdviceProvisions * ~AdviceRequests * (average number of binding terms). But contrary to the standard solutions for rules based systems (either forward or backward chaining), in this case here always complete binding sets are to be matched, which allows to reduce the effort.
+
+!!!solution mechanics
+The binding patterns are organised by //predicate symbol and the lists are normalised.// A simple normalisation could be lexicographic ordering of the predicate symbols. Then the resulting representation can be //hashed.// When all predicates are constant, a match can be detected by hashtable lookup, otherwise, in case some of the predicates contain variable arguments ({{red{planned extension}}}), the lookup is followed by an unification. For this to work, we'll have to include the arity into the predicate symbols used in the first matching stage. Moreover, we'll create a //matching closure// (functor object), internally holding the arguments for unification. This approach allows for //actual interpretation of the arguments.// It is conceivable that in special cases we'll get multiple instances of the same predicate, just with different arguments. The unification of these terms needs to consider each possible pairwise combination (cartesian product) &mdash; but working out the details of the implementation can safely be deferred until we'll actually hit such a special situation, thanks to the implementation by a functor.
+
+Fortunately, the calculation of this normalised patterns can be separated completely from the actual matching. Indeed, we don't even need to store the binding patterns at all within the binding index &mdash; storing the hash value is sufficient (and in case of patterns with arguments we'll attach the matching closure functor). Yet still we need to store a marker for each successful match, together with back-links, in order to handle changing and retracting of advice.
+
+!!!storage and registrations
+We have to provide dedicated storage for the actual advice provisions and for the index entries. Mostly, these objects to be managed are attached through a single link &mdash; and moreover the advice system is considered performance critical, so it doesn't make sense to implement the management of these entries by smart-ptr. This rules out ~TypedAllocationManager and prompts to write a dedicated storage frontend, later to be backed by Lumiera's mpool facility.
+* both the advice provision and the advice requests attach to the advice system after fulfilling some prerequisites; they need to detach automatically on destruction.
+* in case of the provision, there is a cascaded relation: the externally maintained provision creates an internal provision record, which in turn attaches an index entry.
+* both in case of the provision and the request, the relation of the index bears some multiplicity:
+** a multitude of advice provisions can attach with the same binding (which could be the same binding pattern terms, but different variable arguments). Each of them could create a separate advice solution (at least when variable arguments are involved); it would be desirable to establish a defined LIFO order for any search for possibly matching advice.
+** a multitude of advice requests can attach with the same binding, and each of them needs to be visited in case a match is detected.
+* in both cases, any of these entries could be removed any time on de-registration of the corresponding external entity
+* we need to track existing advice solutions, because we need to be able to overwrite with new advice and to remove all solutions bound to a given pattern about to leave the system. One provision could create a large number of solutions, while each registration always holds onto exactly one solution (which could be a default/placeholder solution though)
+
+!!!!subtle variations in semantics
+While generally advice has value semantics and there is no ownership or distinguishable identity, the actual implementation technique creates the possibility for some subtle semantic variations. At the time of this writing (5/2010) no external point of reference was available to decide upon the correct implementation variant. These variations get visible when advice is //retracted.// Ideally, a new advisor would re-attach to an existing provision and supersede the contained advice information with new data. Thus, after a chain of such new provisions all attaching with the identical binding, when finally the advice gets retracted, any advice provisions would be gone and we'd fall back onto the default solution. Thus, "retracting" would mean to void any advice given with this binding.
+But there is another conceivable variation of semantics, which yields some benefits implementation-wise: Advice can be provided as "I don't care what was said, but here is new information". In this case, the mechanism of resolving and finding a match would be responsible to pick the latest addition, while the provisions would just be dumped into the system. In this case, "retracting" would mean just to cancel //one specific//&nbsp; piece of information and might cause in an older advice solution to be uncovered and revived. The default (empty) solution would be used in this case only after retracting all advice provisions.
+
+!!!!implementation variants with respect to attachment and memory management
+Aside from the index, handling of the advice provisions turns out to be tricky.
+* management by ref-count was ruled out due to contention and locality considerations
+* the most straight forward implementation would be for the ~AdviceProvision within the advisor to keep kind of an "inofficial" link to "its" provision, allowing to modify and retract it during the lifetime of the advisor. When going away without retracting (the default behaviour), the provision, as added into the system would remain there as a dangling entry. It is still reachable via the index, but not maintained in any further way. If memory usage turns out to be a problem, we'd need to enqueue these entries for clean-up.
+* but as this simple solution contradicts the general advice semantics in a subtle way (see previous paragraph), we could insist on really re-capturing and retracting previous advice automatically on each new advice provision or modification. In this case, due to the requirement of thread safety, each addition, binding modification, placing of new advice or retraction would require to do an index search to find an existing provision with equivalent binding (same binding definition, not just a matching binding pattern). As a later provision could stomp upon an existing provision without the original advisor noticing this, we can't use the internal references anymore; we really need to search each time and also need a global lock during the modification transaction.
+* an attempt to reduce this considerable overhead would be to use an back-link from the provision as added to the system to the original source (the ~AdviceProvision owned by the advisor). On modification, this original source would be notified and thus detached. Of course this is tricky to implement correctly, and also requires locking.
+The decision for the initial implementation is to use the first variant and just accept the slightly imprecise semantics.
+When copying a Provision, the hidden link to existing advice data is //not shared.//
+
+!!!!de-allocation of advice data
+It is desirable that the dtors of each piece of advice data be called eventually. But ensuring this reliably is tricky, because advice 
+data may be of various types and is added to the system to remain available, even after the original {{{advice::Provision}}} went out of scope. Moreover, the implementation decision was //not//&nbsp; to employ a vtable for the advice collaborators and data holders, so we're bound to invoke the dtor with the correct specific type.
+There are some special cases when de-allocation happens while the original provision is still alive (new advice, changed binding, retracting). But in any other case, responsibility for de-allocation has to be taken by the ~AdviceSystem, which unfortunately can't handle the specific type information. Thus the original provision needs to provide a deleter function, and there is no way to avoid storing a function pointer to this deleter within the ~AdviceSystem, together with the advice data holder.
+It seems reasonable to create this deleter right away and not to share the link to advice data, when copying a provision, to keep responsibilities straight. {{red{Question: does this even work?? }}} to be verified: does the address of the advice data buffer really determine alone what is found as "existing" provision?
+
+!!!lifecycle considerations
+Behind the scenes, hidden within the {{{advice.cpp}}} implementation file, the ~AdviceSystem is maintained as singleton. According to a general lifecycle policy within Lumiera, no significant logic is allowed to execute in the shutdown phase of the application, once the {{{main()}}} has exited. Thus, any advice related operations might throw {{{error::Logic}}} after that point. The {{{~AdviceSystem()}}} also is a good place to free any buffers holding incorporated advice data, after having freed the index datastructure referring to these buffer storage, of course.
+
+!!!!handling of default advice
+Basically, the behaviour when requesting non-existing advice may be configured by policy. But the default policy is to return ref to a default constructed instance of the advice type in that case. Just the (implementation related) problem is that we return advice by {{{const&}}}, not by value, so we're bound to create and manage this piece of default advice during the lifetime of the ~AdviceSystem. The way the ~AdviceSystem is accessed (only through the frontend of {{{advice::Request}}} and {{{advice::Provision}}} objects, in conjunction with the desire to control this behaviour by policy, creates a tricky implementation situation.
+* regarding the lifecycle (and also from the logical viewpoint) it would be desirable to handle this "default" or "no solution" case similar to accessing an existing solution. But unfortunately doing so would require a fully typed context; thus basically on inserting a new request, when returning from the index search without a dedicated solution, we'd need to fabricate a fallback solution to insert it into the provision index, while still holding the index lock. At that point it is not determined if we ever need that fallback solution. Alternatively we could consider to fabricate this fallback solution on first unsuccessful advice fetch. But this seems sill worse, as it turns an (possibly even lock free) ptr access into an index operation. Having a very cheap advice access seems like an asset.
+* on the other hand, using some separate kind of singleton bundle just for these default advice data (e.g. a templated version of //Meyer's Singleton...//), the fallback solution can be settled independent from the ~AdviceSystem, right in the {{{advice.hpp}}} and using static memory, but the downside is now the fallback solution might be destroyed prior to shutdown of the ~AdviceSystem, as it lives in another compilation unit.
+Thus the second approach looks favourable, but we should //note the fact that it is hard to secure this possible access to an already destroyed solution,// unless we decline using the advice feature after the end of {{{main()}}}. Such a policy seems to be reasonable anyway, as the current implementation also has difficulties to prevent accessing an already destroyed {{{advice::Provision}}}, being incorporated in the ~AdviceSystem, but accessed through a direct pointer in the {{{advice::Request}}}.
+
+!!!locking and exception safety
+The advice system is (hopefully) written such as not to be corrupted in case an exception is thrown. Adding new requests, setting advice data on a provision and any binding change might fail due to exhausted memory. The advice system remains operational in this case, but the usual reaction would be //subsystem shutdown,// because the Advice facility typically is used in a very low-level manner, assuming it //just works.// As far as I can see, the other mutation operations can't throw.
+
+The individual operations on the interface objects are //deliberately not thread-safe.// The general assumption is that {{{advice::Request}}} and {{{advice::Provision}}} will be used in a safe environment and not be accessed or modified concurrently. An notable exception to this rule is accessing Advice: as this just includes checking and dereferentiating a pointer, it might be done concurrently. But note, //the advice system does nothing to ensure visibility of the solution within a separate thread.// If this thread still has the old pointer value in his local cache, it won't pick up the new solution. In case the old solution got retracted, this even might cause access to already released objects. You have been warned. So it's probably a good idea to ensure a read barrier happens somewhere in the enclosing usage context prior to picking up a possibly changed advice solution concurrently.
+{{red{TODO}}}: the underlying operations on the embedded global {{{advice::Index}}} obviously need to be protected by locking the whole index table on each mutation, which also ensures a memory barrier and thus propagates changed solutions.
+
+!!!index datastructure
+It is clear by now that the implementation datastrucutre has to serve as a kind of //reference count.// Within this datastructure, any constructed advice solution needs to be reflected somehow, to prevent us from discarding an advice provision still accessible. Allowing lock-free access to the advice solution (planned feature) adds an special twist, because in this case we can't even tell for sure if an overwritten old solution is actually gone (or if its still referred from some thread's cached memeory). This could be addressed with an transactional approach (which might be good anyway) &mdash; but I tend to leave this special concern asside for now.
+
+To start with, any advice matching and solution will //always happen within matching buckets of a hash based pattern organisation.// The binding index thus should build on two hashtables (one for the requests and one for the provisions), but using specifically crafted datastructures as buckets. The individual entries within these bucket structures in both cases will be comprised of a binding matcher (to determine if an match actually happens) and a back-link to the registered entitiy (provision or request). Given the special pattern of the advice solutions, existing solutions could be tracked within the entries at the request side.
+* Advice provisions are expected to happen only in small numbers; they will be searched stack-like, starting from the newes provisions, until a match is found.
+* Each advised entity basically creates an advice request, so there could be a larger number of request entries. In the typical search triggered from the provision side, each request entry will be visited and checked for match, which, if successful, causes a pointer to be set within the ~AdviceRequest object (located outside the realm of the advice system). While &mdash; obviously &mdash; multiple requests with similar binding match could be folded into a sub-list, we need actual timing measurements to determine the weight of these two calculation steps of matching and storing, which together comprise the handling of an advice solution.
+
+The above considerations don't fully solve the question how to represent an computed solution within the index datastructure, candidates being to use the index within the provision list, or a direct pointer to the provision or even just to re-use the pointer stored into the ~AdviceRequest. My decision is to do the latter. Besides solutions found by matching, we need //fallback solutions// holding a default constructed piece of advice of the requested type. As these defaults aren't correlated at all to the involved bindings, but only to the advice type as such, it seems reasonable to keep them completely apart, like e.g. placing them into static memory managed by the ~AdviceProvision template instantiations.
+
+!!!interactions to be served by the index
+[>img[Advice solution|draw/AdviceBindingIndex1.png]]
+
+;add request
+:check existing provisions starting from top until match; use default solution in case no match is found; publish solution into the new request; finally attach the new request entry
+;remove request
+:just remove the request entry
+;modify request
+:handle as if newly added
+;add provision
+:push new provision entry on top; traverse all request entries and check for match with this new provision entry, publish new solution for each match
+;retract provision
+:remove the provision entry; traverse all request entries to find those using this provision as advice solution, treat these as if they where newly added requests
+;modify provision
+:add a new (copy of the) provision, followed by retracting the old one; actually these two traversals of all requests can be combined, thus treating a request which used the old provision but doesn't match the new one is treated like a new request
+<<<
+__Invariant__: each request has a valid soultion pointer set (maybe pointing to a default solution). Whenever such a solution points to a registered provision, there is a match between the index entries and this is the top-most possible match to any provision entry for this request entry
+<<<
+Clearly, retracting advice (and consequently also the modification) is expensive. After finishing these operations, the old/retracted provision can be discarded (or put asside in case of non-locking advice access). Other operations don't cause de-allocation, as provisions remain within the system, even if the original advising entity is gone.
+

+

+

+
From analysing a number of intended AdviceSituations, some requirements for an Advice collaboration and implementation can be extracted.
+
+* the piece of advice is //not shared// between advisor and the advised entities; rather, it is copied into storage managed by the advice system
+* the piece of advice can only be exposed {{{const}}}, as any created advice point solution might be shared
+* the actual mode of advice needs to be configurable by policy &mdash; signals (callback functors) might be used on both sides transparently
+* the client side (the advised entity) specifies initially, if a default answer is acceptable. If not, retrieving advice might block or fail
+* on both sides, the collaboration is initiated specifying an advice binding, which is an conjunction of predicates, --optionally dynamic--^^no!^^
+* there is a tension between matching performance and flexibility. The top level should be entirely static (advice type)
+* the analysed usage situations provide no common denominator on the preferences regarding the match implementation.
+* some cases require just a match out of a small number of tokens, while generally we might get even a double dispatch
+* later, possible and partial solutions could be cached, similar to the rete algorithm. Dispatching a solution should work lock-free
+* advice can be replaced by new advice, which causes all matching advice solutions to behave as being overwritten.
+* when locking is left out, we can't give any guarantee as to when a given advice gets visible to the advised entity
+* throughput doesn't seem to be an issue, but picking up existing advice should be as fast as possible
+* we expect a small number of advisors collaborating with and a larger number of advised entities.
+
+!!questions
+;when does the advice collaboration actually happen?
+:when there is both a client (advised) and a server (advisor) and their advice bindings match
+;can there be multiple matches?
+:within the system as a whole there can be multiple solutions
+:but the individual partners never see more than one connection
+:each point of advice has exactly one binding and can establish one advice channel
+;but when an attempt is made to transfer more information?
+:both sides don't behave symmetrically, and thus the consequences are different
+:on the client side, advice is just //available.// When there is newer one, the previous advice is overwritten
+:the server side doesn't //contain// advice &mdash; rather, it is placed into the system. After that, the advisor can go away
+:thus, if an advisor places new advice into an existing advice provision, this effectively initiates a new collaboration
+:if the new advice reaches the same destination, it overwrites; but it may as well reach a different destination this time
+;can just one advice provision create multiplicity?
+:yes, because of the matching process there could be multiple solutions. But neither the client nor the server is aware of that.
+;can advice be changed?
+:No. When inserted into the system, the advisor looses any direct connection to the piece of advice (it is copied)
+:But an advisor can put up another piece of advice into the same advice provision, thereby effectively overwriting at the destination
+;if advice is copied, what about ownership and identity?
+:advice has //value semantics.// Thus it has no distinguishable identity beyond the binding used to attach it
+:a provision does not "own" advice. It is a piece of information, and the latest information is what counts
+;can the binding be modified dynamically?
+:this is treated as if retracting the existing point of advice and opening a new one.
+;what drives the matching?
+:whenever a new point of advice is opened, search for a matching solution happens.
+:thus, the actual collaboration can be initiated from both sides
+:when a match happens, the corresponding advice point solution gets added into the system
+;what about the lifetime of such a solution?
+:it is tied to the //referral// &mdash; but there is an asymmetry between server and client
+:referral is bound to the server sided / client sided point of advice being still in existence
+:but the server sided point of advice is copied into the system, while the client sided is owned by the client
+:thus, when an advisor goes away without explicitly //retracting//&nbsp; the advice, any actual solution remains valid
+:on the client side there is an asymmetry: actually, a new advice request can be opened, with an exactly identical binding
+:in this case, existing connections will be re-used. But any differences in the binding will require searching a new solution
+;is the search for an advice point solution exhaustive?
+:from the server side, when a new advice provision / binding is put up, //any// possible advice channel will be searched
+:contrary to this, at the client side, the first match found wins and will establish an advice channel.
+
+!decisions
+After considering the implementation possibilities, some not completely determined requirements can be narrowed down.
+* we //do// support the //retracting of advice.//
+* there is always an implicit //default advice solution.//
+* advice //is not an messaging system// &mdash; no advice queue
+* signals (continuations) are acceptable as a extension to be provided later
+* retracting advice means to retreat a specific solution. This might or might not uncover earlier solutions (undefined behaviour)
+* we don't support any kind of dynamic re-evaluation of the binding match (this means not supporting the placement use case)
+* the binding pattern is //interpreted strictly as a conjunction of logic predicates// &mdash; no partial match, but arguments are allowed
+* we prepare for a later extension to //full unification of arguments,// and provide a way of accessing the created bindings as //advice parameters.//
+
+Combining all these requirements and properties provides the foundation for the &rarr; AdviceImplementation
+
+

+

+

+
[[Advice]] is a pattern extracted from several otherwise unrelated constellations
+
+!Proxy media in the engine
+Without rebuilding the engine network, we need the ability to reconfigure some parts to adapt to low resolution place-holder media temporarily. The collaboration required to make this happen seems to ''cross-cut'' the normal processing logic. Indeed, the nature of the adjustments is highly context dependent &mdash; not every processing node needs to be adjusted. There is a dangerous interference with the ongoing render processes, prompting for the possibility to pick up this information synchronously.
+* the addressing and delivery of the advice is based on a mix of static (type) and dynamic information
+* it is concievable that the actual matching may even include a token present in the direct invocation context (but this possibility was ruled out by later decision)
+* the attempt to recieve and pick up advice needs to be failsafe
+* locking should be avoided by design
+
+!Dependency injection for testing
+While inversion of control is a guiding principle on all levels, the design of the Lumiera application deliberately stays just below the level of employing a dependency injection container. Instead, common services are accessible //by type// and the builder pattern is used more explicitly at places. Interestingly, the impact on writing unit tests was by far not so serious as one might expect, based on the usual reasoning of D.I. proponents. But there remain some situations, where sharing a common test fixture would come in handy
+* here the test depending on a fixture puts up a hard requirement for the actual advice to be there.
+* thus, the advice support system can be used to communicate a need for advice
+* but it seems unreasonable to extend it actually to transmitt a control flow
+
+!properties of placement
+The placement concept plays a fundamental role within Lumiera's HighLevelModel. Besides just being a way of sticking objects together and defining the common properties of //temporal position and output destination,// we try to push this approach to enable a more general, open and generic use. "Placement" is understood as locating within a grid comprised of various degrees of freedom &mdash; where locating in a specific way might create additional dimensions to be included into the placement. The standard example is an output connection creating additional adjustable parameters controlling the way the connected object is embedded into a given presentation space (consider e.g. a sound object, which &mdash; just by connection, gains the ability of being //panned// by azimuth, elevation and distance)
+* in this case, obviously the colaboration is n:m, while each partner preferrably should only see a single advice link.
+* advice is used here to negotiate a direct colaboration, which is then handed off to another facility (wiring a control connection)
+* the possibility of an advice colaboration in this case is initiated rather from the side of the advisor
+* deriving an advice point solution includes some kind of negotioation or active re-evaluation
+* the possible adivsors have to be queried according to their placement scope relations
+* this queriying might even trigger a resolution process within the advising placement.
+__Note__: after detailed analysis, this use case was deemed beyond the scope of the [[Advice]] core concept and idea.
+//As a use case, it was dropped.// But we retain some of the properties discovered by considering this scenario, especially the n:m relation, the symmetry in terms of opening the collaboration, and the possibility to have a specially implemented predicate in the binding pattern.
+
+&rarr; AdviceRequirements
 

 

 

@@ -3293,7 +3493,7 @@ probably a LocatingPin but... {{red{TODO any details are yet unknown as of 5/08}
 !querying additional dimensions
 basically you resolve the Placement, yielding an ExplicitPlacement... {{red{TODO but any details of how additional dimensions are resolved is still undefined as of 5/08}}}
-
+
[[Placement]]s are at the very core of all [[editing operations|EditingOperations]], because they act as handles (smart pointers) to access the [[media objects|MObject]] to be manipulated. Placements themselves are lightweight and can be handled with //value semantics//. But, when adding a Placement to the [[Session]], it gains an distinguishable identity and should be treated by reference from then on: changing the location properties of this placement has a tangible effect on the way the placed object appears in the context of the session. Besides the direct (language) references, there is a special PlacementRef type which builds on this registration of the placement within the session, can be represented as POD and thus passed over external interfaces. Many editing tasks include finding some Placement in the session and reference as parameter. By acting //on the Placement object,// we can change parameters of the way the media object is placed (e.g. adjust an offset), while by //dereferencing//&nbsp; the Placement object, we access the "real" media object (e.g. for trimming its length). Placements are ''templated'' on the type of the actual ~MObject they refer to, thus defining the interface/methods usable on this object.
 
 Actually, the way each Placement ties and locates its subject is implemented by one or several small LocatingPin objects, where subclasses of LocatingPin implement the various different methods of placing and resolving the final location. Notably, we can give a ~FixedLocation or we can atach to another ~MObject to get a ~RelativeLocation, etc. In the typical use case, these ~LocatingPins are added to the Placement, but never retrieved directly. Rather the Placement acts as a ''query interface'' for determining the location of the related object. Here, "location" can be thought of as encompassing multiple dimenstions at the same time. An object can be
Advice solving
EDL Example1A simple example showing how the actual objects are placed in the Fixture (=definitive playlist). It shows a Video and Audio clip placed on two tracks
EDL Example2More complex example showing the Object graph in the EDL and how it is linked into the Fixture to yield the actual locations. In this example, an HUE Effect is applied on a part of the Clip
Engine Example1Example1 (from EDL) continued: here the RenderEngine to be created by the Builder from the Input shown in Example1
findTypeHandler
getAppconfigaccess the configuation value for a given key.
@return empty string for unknown keys, else the corresponding configuration value
get_reprAllocation
getAdviceRequest
getAssetAssetManagerfind and return corresponging object
getAutomationFixture
getConnectionConManagerTODO
retrieveStateAdapter
rootCauseErrorIf this exception was caused by a chain of further exceptions,
return the first one registered in this throw sequence.
This works only, if every exceptions thrown as a consequence
of another exception is propperly constructed by passing
the original exception to the constructor
saveSessManagercreate a complete, serialized representation
of the current session config and contents.
@todo how to serialize, prameters, return value?
setAdviceProvision
treatApplicable
treatBuilderToolThis operation is to be overloaded for the specific MObject subclasses to be treated.
treatNodeCreatorTool
treatNodeCreatorTool
treatNodeCreatorTool
treatNodeCreatorTool
treatSegmentationTool
treatNodeCreatorTool
treatNodeCreatorTool
treatNodeCreatorTool
treatSegmentationTool
treatSegmentationTool
treatSegmentationTool
useFileFileProviderAnnounces that the application intends to use this file with mode (READ|WRITE|READWRITE)
useTemporaryStorageFileProviderProvides a pool for interminate frames
whatError