doc/Parser.md

@@ -63,7 +63,7 @@ Since the media library is built without (lib)vlc support for desktop platforms,
 
 The resulting metadata are serialized and exposed through the `parser::IItem` interface, in order to provide a common way of accessing the results throughout the rest of the pipeline.
 
-:warning: The extraction task will systematically run as long as the task isn't entirely completed. This is because the rest of the services assume that they have all the information required to do their processing. In theory this requirement could be lifted for some linking tasks, as they are likely not to depend on the metadata themselves, but rather the information stored in database.
+:warning: In the case of a non-linking task, the extraction task will systematically run as long as the task isn't entirely completed. This is because the rest of the services assume that they have all the information required to do their processing. This means that the extraction step completion is *never* stored in database but only in memory.
 
 Metadata Analysis
 -----------------
@@ -92,4 +92,27 @@ The linking step was separated from the rest of the pipeline in order to simplif
 By having a task dedicated to linking, we can postpone a task until later, once we know we have  the required entities in database. This is done by returning `Requeue` as a status from the `Service::run` member function.
 
 Tasks in database
-=================
\ No newline at end of file
+=================
+
+The tasks must live in database in order for them to be restarted, be it following a crash, loss of power, or any other way for the entire parsing not to complete.
+
+It also allows to force full rescan simply by resetting the completion flag of each task in database, which is heavily used during migrations.
+
+Tasks are stored in the `Task` table, and contains multiple fields both in database, and in memory.
+
+The database focuses on storing the IDs of the related entities, while the in-memory instance might also store the entities associated with those IDs, through the `Task::restoreLinkedEntities` helper. Linking tasks have no associated in-memory entities as they solely consists of an ID and a MRL. Since these values are only used by the linking service, it is responsible for fetching whatever it needs to link the 2 entities together.
+
+On the other hand, when parsing for an album for instance, the instances representing the file or containing folder on disk are likely to be used multiple times, so we fetch them once during the task startup.
+
+The fields are:
+- `id_task` which is simply the primary key
+- `step` which represents the current step for this task. This is the field used to fetch all uncompleted tasks. The value is expected to be a `parser::Step`
+- `attempts_left` stores a counter of the remaining attempt for each tasks. This can differ depending on the task types. Once it reaches 0, the task is considered as failed and will not be restarted automatically, but the application may explicitly ask for those tasks to be restarted
+- `type` which stored the kind of task this is. This is represented by the `parser::Task::Type` enum, and can be one of `Creation` when the task originates from a new file being discoved, `Link` when linking 2 entities together, `Refresh` when the file was detected as modified on disk, and `Restore` which is an internal type used for restoring playlist backups.
+- `mrl` this represents the MRL of the item being analyzed
+- `file_type` represented by the `IFile::Type` enum. The value comes from the metadata extraction step and will usually condition the type of analysis that will be performed.
+- `file_id` stores the ID of the file that was created following an analysis step. If the file was not created yet, this will be 0. If the value isn't 0 when restoring a task, the associated `File` instance will be cached locally
+- `parent_folder_id` stored the ID of the folder that contained the analyzed file. When the task is of `Creation` type, this value is mandatory
+- `link_to_id` & `link_to_type` describe the type & ID of the entity the item pointed by this task (stored at the given `mrl`) must be linked to.
+- `link_extra` Optional value which depend on the context. This is used for storing the position of a playlist item when spawning the linking tasks.
+- `link_to_mrl`: When the link tasks are spawned, the item being linked might not be created yet, so we store the MRL instead of an identifier. This is used to fetch the media that we will need to link
\ No newline at end of file