diff --git a/en/chap03.tex b/en/chap03.tex index 34c1756..af94e57 100644 --- a/en/chap03.tex +++ b/en/chap03.tex @@ -191,8 +191,85 @@ possibility.) \section{Annotations} -\XXX{scoping, annotator creation, advantages of storing data in annotations and -not vertices. Annotator protocol and posibility of export. Various uses of annotators: enhancing, analysis, visualisation. heapq} +Once a TopologyV3 is obtained, it may be annotated. An Annotator may create an +Annotation, which is then stored as a part of an AnnotatedTopology. We now +explore design of these objects in detail. + +An Annotation is essentially only a holder for any \uv{tags} that are to be +attached to the topology. These are represented by a dictionary holding +annotations for Vertices, another dictionary for annotating Edges, and a single +field allowing the attachment of a tag to the entire Topology. The keys of the +dictionaries are VertexIDs and Edges, respectively. + +The Annotation can only attach one tag to each vertex and edge, but there are +little restrictions of what the tag is allowed to be. The intention is to allow +Annotators to provide any useful data they can collect. However, we think that +our AnnotatedTopologies could be utilised in other projects, so the Annotation +objects ought to be easy to serialise into JSON or other formats. + +Annotations do not need to take other Annotations into account, because +AnnotatedTopology stores Annotations from different Annotators separately. + +The Annotators are a tiny bit more interesting. While these objects are +basically a wrapper around the \verb|annotate()| method, which takes an +AnnotatedTopology and returns an Annotation, there are few twists to it. + +First, an Annotator object is intended to be created by the respective +AnnotatedTopology in order for it to keep track of all the Annotators. To +describe an Annotator, an AnnotatorID is used, which is a re-creatable and +hashable recipe for creating that Annotator. It is also used as a handle to +reference and scope the resulting Annotation. The AnnotatorID is a pair of the +type object of the particular Annotator, and an optional hashable parameter, +which is passed to the Annotator's initialiser. + +Second, an Annotator might require another Annotator to have already run. We +make this possible by allowing Annotators to request another Annotator to be +run by the AnnotatedTopology (provided the AnnotatorID), as long as there is +not a dependency cycle. This is the recommended method of implementing +dependencies of Annotators. + +Furthermore, an Annotator can be declared to be idempotent. This affects what +happens when the same Annotator is invoked on the same Topology in the same way +(that is, using the same AnnotatorID) multiple times. For idempotent +Annotators, we know that their output will not change, so the Annotator is not +really run. For non-idempotent Annotators, the previous Annotation is removed +and the Annotator is run again. + +Annotators may not alter the AnnotatedTopology in any way. They are only +allowed to return an Annotation, which will be added to the AnnotatedTopology. +As with frozen Topologies, this is not enforced by the code. + +Annotators may be used for various tasks, including but not limited to +performing analysis of the Topology, enhancing it with additional data (e.g. +ping response times from other system), or specifying parameters for +visualisation. As a part of Birdvisu itself, we ship several anotators: +TopologyDifference outputs the differences between the reference and current +Topology, and ShortestPathTree marks the edges of the shortest path DAG. + +The last important object related to annotation is the AnnotatedTopology. It +serves as a coordinator for running Annotators. It does two main things: +detects dependency cycles between Annotators, and keeps the Annotations. + +The Annotations in the AnnotatedTopology are stored in a dictionary indexed by +the respective AnnotatorID. For vertices and edges, only sets of AnnotatorIDs +are stored. This way, both iterating Annotations for a Vertex or Edge and +examining individual Annotations is fast. Also, our approach isolates unrelated +Annotations by putting them into different scopes by AnnotatorID. + +However, by using the Annotator's type in AnnotatorID, this design enforces a +rather tight coupling between Annotators and users of Annotations, because the +consumers of Annotations need to understand the precise format of the +particular Annotation. This could be solved by implementing support for +\uv{interface-annotators}, so that various Annotators may provide Annotations +in a commonly understood format.\footnote{Preliminary work on implementing this +approach is present in the \texttt{ann\_interfaces} branch, but the interaction of +implementers of the same interface is not decided yet.} + +AnnotatedTopology does not expose a way to delete old Annotations. While we do +not expect this to cause big memory leaks, in case it does, an LRU-like +strategy might be employed to tame the memory usage. Also, the Annotators could +be run dynamically when the Annotation is requested, but our current approach +does not need this functionality, so it is not implemented at the moment. \section{Visualisation} diff --git a/en/header.tex b/en/header.tex index 1492a41..dc5ee84 100644 --- a/en/header.tex +++ b/en/header.tex @@ -86,17 +86,20 @@ % An optional dedication: you can thank whomever you wish (your supervisor, % consultant, a person who lent the software, etc.) \def\Dedication{% -Dedication. +I would like to thank my friends, colleagues and family for nudging and convincing me enough to finish my studies. + +Naturally, I would also like to thank my supervisor Martin Mareš, for being hopeful and patient and for teaching me many useful skills. + +Last, but not least, I want to thank You, my dear reader, because right now You are making sure this thesis was worth writing. } -% Abstract (recommended length around 80-200 words; this is not a copy of your thesis assignment!) \def\Abstract{% Abstract. \X{Recommended length around 80--200 words. This is not a~copy of your thesis assignment!} } % 3 to 5 keywords (recommended), each enclosed in curly braces \def\Keywords{% -{key} {words} \X{usually 3 to~5 key words or phrases} +{OSPF} {network visualisation} {BIRD} {routing} } %% The hyperref package for clickable links in PDF and also for storing