libfossil
fsl_deck Struct Reference

A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Structural Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Structural Artifact of an arbitrary type, e.g. More...

#include "repo.h"

Collaboration diagram for fsl_deck:

Data Fields

struct { 
   char *   name 
 Filename of the A-card. More...
   fsl_uuid_str   src 
 UUID of the file being attached via the A-card. More...
   char *   tgt 
 Name of wiki page, or UUID of ticket or event (technote), to which the attachment applies. More...
} A
 The 'A' (attachment) card.
void const * allocStamp
 A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in which case fsl_deck_finalize() will fsl_free() it) or not (in which case it does not fsl_free() it).
struct { 
   fsl_deck *   baseline 
 Baseline manifest corresponding to this->B. More...
   fsl_uuid_str   uuid 
 The 'B' (baseline) card holds the UUID of baseline manifest. More...
} B
char * C
 The 'C' (comment) card.
fsl_buffer content
 This is part of an optimization used when parsing fsl_deck instances from source text.
double D
 The 'D' (date) card, in Julian format.
struct { 
   double   julian 
 The 'E' card's date in Julian Day format. More...
   fsl_uuid_str   uuid 
 The 'E' card's UUID. More...
} E
 The 'E' (event) card.
fsl_card_F_list F
 The 'F' (file) card container.
fsl_cx * f
 The Fossil context responsible for this deck.
fsl_uuid_str G
 UUID for the 'G' (forum thread-root) card.
char * H
 The H (forum title) card.
fsl_uuid_str I
 UUID for the 'I' (forum in-response-to) card.
fsl_list J
 The 'J' card specifies changes to "value" of "fields" in tickets (FSL_SATYPE_TICKET).
fsl_uuid_str K
 UUID for the 'K' (ticket) card.
char * L
 The 'L' (wiki name/title) card.
fsl_list M
 List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).
char * N
 The 'N' (comment mime type) card.
fsl_deck * next
 To potentially be used for a manifest cache.
fsl_list P
 List of UUIDs of parents ('P' cards).
fsl_list Q
 'Q' (cherry pick) cards.
char * R
 The R-card holds an MD5 hash which is calculated based on the names, sizes, and contents of the files included in a manifest.
fsl_id_t rid
 DB repo.blob.rid value.
fsl_list T
 List of 'T' (tag) cards.
fsl_satype_e type
 Specifies the the type (or eventual type) of this artifact.
char * U
 The U (user) card.
fsl_buffer W
 The W (wiki content) card.

Detailed Description

A "deck" stores (predictably enough) a collection of "cards." Cards are constructs embedded within Fossil's Structural Artifacts to denote various sorts of changes in a Fossil repository, and a Deck encapsulates the cards for a single Structural Artifact of an arbitrary type, e.g.

Manifest (a.k.a. "checkin") or Cluster. A card is basically a command with a single-letter name and a well-defined signature for its arguments. Each card is represented by a member of this struct whose name is the same as the card type (e.g. fsl_card::C holds a C-card and fsl_card::F holds a list of F-card). Each type of artifact only allows certain types of card. The complete list of valid card/construct combinations can be found here:

https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki#summary

fsl_card_is_legal() can be used determine if a given card type is legal (per the above chart) with a given Control Artifiact type (as stored in the fsl_deck::type member).

The type member is used by some algorithms to determine which operations are legal on a given artifact type, so that they can fail long before the user gets a chance to add a malformed artifact to the database. Clients who bypass the fsl_deck APIs and manipulate the deck's members "by hand" (so to say) effectively invoke undefined behaviour.

The various routines to add/set cards in the deck are named fsl_deck_CARDNAME_add() resp. fsl_deck_CARDNAME_set(). The "add" functions represent cards which may appear multiple times (e.g. the 'F' card) or have multiple values (the 'P' card), and those named "set" represent unique or optional cards. The R-card is the outlier, with fsl_deck_R_calc(). NEVER EVER EVER directly modify a member of this struct - always use the APIs. The library performs some optimizations which can lead to corrupt memory and invalid free()s if certain members' values are directly replaced by the client (as opposed to via the APIs).

Note that the 'Z' card is not in this structure because it is a hash of the other inputs and is calculated incrementally and appended automatically by fsl_deck_output().

All non-const pointer members of this structure are owned by the structure instance unless noted otherwise (the fsl_deck::f member being the notable exception).

Maintenance reminder: please keep the card members alpha sorted to simplify eyeball-searching through their docs.

See also
fsl_deck_malloc()
fsl_deck_init()
fsl_deck_parse()
fsl_deck_load_rid()
fsl_deck_finalize()
fsl_deck_clean()
fsl_deck_save()
fsl_deck_A_set()
fsl_deck_B_set()
fsl_deck_C_set()
fsl_deck_D_set()
fsl_deck_E_set()
fsl_deck_F_add()
fsl_deck_J_add()
fsl_deck_K_set()
fsl_deck_L_set()
fsl_deck_M_add()
fsl_deck_N_set()
fsl_deck_P_add()
fsl_deck_Q_add()
fsl_deck_R_set()
fsl_deck_T_add()
fsl_deck_branch_set()
fsl_deck_U_set()
fsl_deck_W_set()

Definition at line 319 of file repo.h.

Field Documentation

◆ [struct]

struct { ... } fsl_deck::A

The 'A' (attachment) card.

Only used by FSL_SATYPE_ATTACHMENT decks. The spec currently specifies only 1 A-card per manifest, but conceptually this could/should be a list.

◆ allocStamp

void const* fsl_deck::allocStamp

A marker which tells fsl_deck_finalize() whether or not fsl_deck_malloc() allocated this instance (in which case fsl_deck_finalize() will fsl_free() it) or not (in which case it does not fsl_free() it).

Definition at line 523 of file repo.h.

◆ [struct]

struct { ... } fsl_deck::B

◆ baseline

fsl_deck* fsl_deck::baseline

Baseline manifest corresponding to this->B.

It is loaded on demand by routines which need it, typically by calling fsl_deck_F_rewind() (unintuitively enough!). The parent/child relationship in Fossil is the reverse of conventional - children own their parents, not the other way around. i.e. this->baseline will get cleaned up when the child part of that relationship is cleaned up.

Definition at line 388 of file repo.h.

◆ C

char* fsl_deck::C

The 'C' (comment) card.

Definition at line 393 of file repo.h.

◆ content

fsl_buffer fsl_deck::content

This is part of an optimization used when parsing fsl_deck instances from source text.

For most types of card we re-use string values in the raw source text rather than duplicate them, and that requires storing the original text (as passed to fsl_deck_parse()). This requires that clients never tinker directly with values in a fsl_deck, in particular never assign over them or assume they know who allocated the memory for that bit.

Definition at line 510 of file repo.h.

◆ D

double fsl_deck::D

The 'D' (date) card, in Julian format.

Definition at line 398 of file repo.h.

◆ [struct]

struct { ... } fsl_deck::E

The 'E' (event) card.

◆ F

fsl_card_F_list fsl_deck::F

The 'F' (file) card container.

Definition at line 418 of file repo.h.

◆ f

fsl_cx* fsl_deck::f

The Fossil context responsible for this deck.

Though this data type is normally, at least conceptually, free of any given fossil context, many related algorithms need a context in order to perform db- or caching-related work, as well as to simplify error message propagation. We store this as a struct member to keep all such algorithms from redundantly requiring both pieces of information as arguments.

This object does not own the context and the context object must outlive this deck instance.

Definition at line 346 of file repo.h.

◆ G

fsl_uuid_str fsl_deck::G

UUID for the 'G' (forum thread-root) card.

Definition at line 423 of file repo.h.

◆ H

char* fsl_deck::H

The H (forum title) card.

Definition at line 428 of file repo.h.

◆ I

fsl_uuid_str fsl_deck::I

UUID for the 'I' (forum in-response-to) card.

Definition at line 433 of file repo.h.

◆ J

fsl_list fsl_deck::J

The 'J' card specifies changes to "value" of "fields" in tickets (FSL_SATYPE_TICKET).

Holds (fsl_card_J*) entries.

Definition at line 441 of file repo.h.

◆ julian

double fsl_deck::julian

The 'E' card's date in Julian Day format.

Definition at line 407 of file repo.h.

◆ K

fsl_uuid_str fsl_deck::K

UUID for the 'K' (ticket) card.

Definition at line 446 of file repo.h.

◆ L

char* fsl_deck::L

The 'L' (wiki name/title) card.

Definition at line 451 of file repo.h.

◆ M

fsl_list fsl_deck::M

List of UUIDs (fsl_uuid_str) in a cluster ('M' cards).

Definition at line 456 of file repo.h.

◆ N

char* fsl_deck::N

The 'N' (comment mime type) card.

Note that this is only ostensibly supported by fossil, but fossil does not (as of 2021-04-13) honor this value and always assumes that its value is "text/x-fossil-wiki".

Definition at line 464 of file repo.h.

◆ name

char* fsl_deck::name

Filename of the A-card.

Definition at line 357 of file repo.h.

◆ next

fsl_deck* fsl_deck::next

To potentially be used for a manifest cache.

Definition at line 515 of file repo.h.

◆ P

fsl_list fsl_deck::P

List of UUIDs of parents ('P' cards).

Entries are of type (fsl_uuid_str).

Definition at line 470 of file repo.h.

◆ Q

fsl_list fsl_deck::Q

'Q' (cherry pick) cards.

Holds (fsl_card_Q*) entries.

Definition at line 475 of file repo.h.

◆ R

char* fsl_deck::R

The R-card holds an MD5 hash which is calculated based on the names, sizes, and contents of the files included in a manifest.

See the class-level docs for a link to a page which describes how this is calculated.

Definition at line 483 of file repo.h.

◆ rid

fsl_id_t fsl_deck::rid

DB repo.blob.rid value.

Normally set by fsl_deck_load_rid().

Definition at line 332 of file repo.h.

◆ src

fsl_uuid_str fsl_deck::src

UUID of the file being attached via the A-card.

Definition at line 368 of file repo.h.

◆ T

fsl_list fsl_deck::T

List of 'T' (tag) cards.

Holds (fsl_card_T*) instances.

Definition at line 488 of file repo.h.

◆ tgt

char* fsl_deck::tgt

Name of wiki page, or UUID of ticket or event (technote), to which the attachment applies.

Definition at line 363 of file repo.h.

◆ type

fsl_satype_e fsl_deck::type

Specifies the the type (or eventual type) of this artifact.

The function fsl_card_is_legal() can be used to determined if a given card type is legal for a given value of this member. APIs which add/set cards use that to determine if the operation requested by the client is semantically legal.

Definition at line 327 of file repo.h.

◆ U

char* fsl_deck::U

The U (user) card.

Definition at line 493 of file repo.h.

◆ uuid

fsl_uuid_str fsl_deck::uuid

The 'B' (baseline) card holds the UUID of baseline manifest.

The 'E' card's UUID.

This is empty for baseline manifests and holds the UUID of the parent for delta manifests.

Definition at line 377 of file repo.h.

◆ W

fsl_buffer fsl_deck::W

The W (wiki content) card.

Definition at line 498 of file repo.h.


The documentation for this struct was generated from the following file: