libfossil
fsl_cx Struct Reference

The main Fossil "context" type. More...

#include "fossil-internal.h"

Data Fields

void const * allocStamp
 Marker which tells us whether fsl_cx_finalize() needs to fsl_free() this instance or not. More...
 
struct {
   int   allowSymlinks
 Cached copy of the allow-symlinks config option, because it is needed on each stat() call. More...
 
   fsl_acache   arty
 Artifact cache used during processing of manifests. More...
 
   char   caseInsensitive
 If true, SOME repository-level file-name comparisons/searches will work case-insensitively. More...
 
   char   deferCrosslink
 Analog to v1's content.c:ignoreDephantomizations flag. More...
 
   struct {
      fsl_list   binary
 Holds the "binary-glob" globs. More...
 
      fsl_list   crnl
 Holds the "crnl-glob" globs. More...
 
      fsl_list   ignore
 Holds the "ignore-glob" globs. More...
 
   }   globs
 Holds various glob lists. More...
 
   char   ignoreDephantomizations
 Porting artifact. More...
 
   char   inFinalVerify
 Used to tell the content-save internals that a "final verification" (a.k.a. More...
 
   char   isCrosslinking
 True if fsl_mf_crosslink_begin() has been called but fsl_mf_crosslink_end() is still pending. More...
 
   fsl_id_bag   leafCheck
 Used during the processing of manifests to keep track of "leaf checks" which need to be done downstream. More...
 
   char   markPrivate
 Bool flag: whether or not a running commit process should be marked as private. More...
 
   struct {
      fsl_deck *   head
 Head of the cache list. More...
 
      fsl_uint32_t   limit
 TODO: maximum number of entries in the mf linked list. More...
 
      fsl_uint32_t   size
 Current number of entries in the mf linked list. More...
 
   }   mf
 TODO: a cache of most recently loaded/freed manifests, analog to v1's manifest.c:manifestCache array. More...
 
   fsl_id_bag   mfSeen
 Used during manifest parsing. More...
 
   fsl_id_t   mtimeManifest
 Infrastructure for fsl_mtime_of_manifest_file(). More...
 
   char *   projectCode
 The "project-code" config option. More...
 
   fsl_id_t   rcvId
 Record ID of rcvfrom entry during commits. More...
 
   int   seenManifest
 Indicates whether or not this repo has ever seen a manifest. More...
 
   fsl_id_bag   toVerify
 Holds the RID of every record awaiting verification during the verify-at-commit checks. More...
 
   char   xlinkClustersOnly
 Flag indicating that only cluster control artifacts should be processed by manifest crosslinking. More...
 
cache
 A place for caching generic things. More...
 
struct {
   int   hasSetupVfile
 Tells us if vfile_selected has been created or not. More...
 
   fsl_deck   mf
 The deck used for incrementally building certain parts of a checkin. More...
 
   fsl_id_bag   selectedIds
 Holds a list of "selected files" in the form of vfile.id values. More...
 
ckin
 State for incrementally proparing a checkin operation. More...
 
struct {
   fsl_db   db
 Handle to the currently opened checkout database IF the checkout is the main db. More...
 
   char *   dir
 Possibly not needed, but useful for doing absolute-to-relative path conversions for checking file lists. More...
 
   fsl_size_t   dirLen
 Optimization: fsl_strlen() of dir. More...
 
   fsl_id_t   rid
 The rid of the current checkout. More...
 
   fsl_uuid_str   uuid
 The UUID of the current checkout. More...
 
ckout
 Holds info directly related to a checkout database. More...
 
fsl_state clientState
 Can be used to tie client-specific data to the context. More...
 
struct {
   fsl_db   db
 Handle to the currently opened global config database IF config is the main db. More...
 
config
 Holds info directly related to a global config database. More...
 
fsl_cx_config cxConfig
 A copy of the config object passed to fsl_cx_init() (or some default). More...
 
fsl_dbdbMain
 A pointer to the "main" db handle. More...
 
fsl_db dbMem
 A ":memory:" (or "") db to work around open-vs-attach-vs-main-vs-real-name problems wrt to the repo/ckout/config dbs. More...
 
fsl_error error
 Holds error state. More...
 
fsl_buffer fileContent
 A place for holding file content. More...
 
int flags
 Flags, some (or one) of which is runtime-configurable by the client (see fsl_cx_flag_t). More...
 
fsl_buffer fsScratch
 A scratchpad specifically for dealing with filename-related, non-recursive caching. More...
 
fsl_outputer output
 Output channel used by fsl_output() and friends. More...
 
struct {
   fsl_db   db
 Handle to the currently opened repository database IF repo is the main db. More...
 
   char *   user
 The default user name, for operations which need one. More...
 
repo
 Holds info directly related to a repo database. More...
 
fsl_buffer scratch
 Optimization: reusable scratchpad for creating/encoding/decoding strings. More...
 
struct {
   fsl_list   customFields
 Holds a list of (fsl_card_J*) records representing custom ticket table fields available in the db. More...
 
   int   hasChng
 Gets set to true (at some point) if the client has the ticketchnk db table. More...
 
   int   hasChngRid
 Gets set to true (at some point) if the client has the ticketchng.rid db field. More...
 
   int   hasCTime
 Gets set to true (at some point) if the client has the ticket.tkt_ctime db field. More...
 
   int   hasTicket
 Gets set to true (at some point) if the client has the ticket db table. More...
 
ticket
 Ticket-related information. More...
 
fsl_xlinker_list xlinkers
 List of callbacks for deck crosslinking purposes. More...
 

Detailed Description

The main Fossil "context" type.

This is the first argument to many Fossil library API routines, and holds all state related to a checkout and/or repository and/or global fossil configuration database(s).

An instance's lifetime looks something like this:

int rc;
fsl_cx * f = NULL; // ALWAYS initialize to NULL or results are undefined
rc = fsl_cx_init( &f, NULL );
assert(!rc);
rc = fsl_repo_open( f, "myrepo.fsl" );
...use the context, and clean up when done...
fsl_cx_finalize(f);

The contents of an fsl_cx instance are strictly private, for use only by APIs in this library. Any client-side dependencies on them will lead to undefined behaviour at some point.

Design note: this type is currently opaque to client code. Having it non-opaque also has advantages, though, and i'd generally prefer that (to allow client-side allocation and embedding in other structs). Binary compatibility concerns might force us to keep it opaque.

Definition at line 249 of file fossil-internal.h.

Field Documentation

void const* fsl_cx::allocStamp

Marker which tells us whether fsl_cx_finalize() needs to fsl_free() this instance or not.

Definition at line 276 of file fossil-internal.h.

int fsl_cx::allowSymlinks

Cached copy of the allow-symlinks config option, because it is needed on each stat() call.

Negative value=="not yet determined", 0==no, positive==yes. The negative value means we need to check the repo config resp. the global config to see if this is on. We can probably default this to true, though i don't think(?) fossil(1) does so(?).

Definition at line 446 of file fossil-internal.h.

fsl_acache fsl_cx::arty

Artifact cache used during processing of manifests.

Definition at line 524 of file fossil-internal.h.

fsl_list fsl_cx::binary

Holds the "binary-glob" globs.

Definition at line 564 of file fossil-internal.h.

struct { ... } fsl_cx::cache

A place for caching generic things.

char fsl_cx::caseInsensitive

If true, SOME repository-level file-name comparisons/searches will work case-insensitively.

Definition at line 452 of file fossil-internal.h.

struct { ... } fsl_cx::ckin

State for incrementally proparing a checkin operation.

struct { ... } fsl_cx::ckout

Holds info directly related to a checkout database.

fsl_state fsl_cx::clientState

Can be used to tie client-specific data to the context.

Its finalizer is called when fsl_cx_finalize() cleans up.

Definition at line 383 of file fossil-internal.h.

struct { ... } fsl_cx::config

Holds info directly related to a global config database.

fsl_list fsl_cx::crnl

Holds the "crnl-glob" globs.

Definition at line 568 of file fossil-internal.h.

fsl_list fsl_cx::customFields

Holds a list of (fsl_card_J*) records representing custom ticket table fields available in the db.

Each entry's flags member denote (using fsl_card_J_flags) whether that field is used by the ticket or ticketchng tables.

TODO, eventually: add a separate type for these entries. We use fsl_card_J because the infrastructure is there and they provide what we need, but fsl_card_J::flags only exists for this list. A custom type would be smaller than fsl_card_J (only two members) but adding it requires adding some infrastructure which isn't worth the effort at the moment.

Definition at line 591 of file fossil-internal.h.

fsl_cx_config fsl_cx::cxConfig

A copy of the config object passed to fsl_cx_init() (or some default).

Definition at line 420 of file fossil-internal.h.

fsl_db fsl_cx::db

Handle to the currently opened checkout database IF the checkout is the main db.

Handle to the currently opened global config database IF config is the main db.

Handle to the currently opened repository database IF repo is the main db.

Definition at line 295 of file fossil-internal.h.

fsl_db* fsl_cx::dbMain

A pointer to the "main" db handle.

Exactly which db IS the main db is, because we have three DBs, not generally knowble.

As of this writing (20141027) the following applies:

dbMain always points to &this->dbMem (a ":memory:" db opened by fsl_cx_init()), and the repo/ckout/config DBs get ATTACHed to that one. Their separate handles (this->{repo,ckout,config}.db) are used to store the name and file path to each one (even though they have no real db handle associated with them).

Internal code should rely as little as possible on the actual arrangement of internal DB handles, and should use fsl_cx_db_repo(), fsl_cx_db_checkout(), and fsl_cx_db_config() to get a handle to the specific db they want. Currently they will always return NULL or the same handle, but that design decision might change at some point, so the public API treats them as separate entities.

Definition at line 270 of file fossil-internal.h.

fsl_db fsl_cx::dbMem

A ":memory:" (or "") db to work around open-vs-attach-vs-main-vs-real-name problems wrt to the repo/ckout/config dbs.

This db handle gets opened automatically at startup and all others which a fsl_cx manages get ATTACHed to it.

Definition at line 285 of file fossil-internal.h.

char fsl_cx::deferCrosslink

Analog to v1's content.c:ignoreDephantomizations flag.

Definition at line 473 of file fossil-internal.h.

char* fsl_cx::dir

Possibly not needed, but useful for doing absolute-to-relative path conversions for checking file lists.

The directory part of an opened checkout db. This is currently only set by fsl_checkout_open_dir(). It contains a trailing slash, largely because that simplifies porting fossil(1) code.

Definition at line 305 of file fossil-internal.h.

fsl_size_t fsl_cx::dirLen

Optimization: fsl_strlen() of dir.

Guaranteed to be set to dir's length if dir is not NULL.

Definition at line 310 of file fossil-internal.h.

fsl_error fsl_cx::error

Holds error state.

As a general rule, this information is updated only by routines which need to return more info than a simple integer error code. This is primarily db-related routines, where we add the db-driver-provided error state here. It is not used by "simple" routines for which an integer code always suffices. APIs which set this should denote it with a comment like "updates the context's error state on error."

Definition at line 395 of file fossil-internal.h.

fsl_buffer fsl_cx::fileContent

A place for holding file content.

We use this in places where we have to loop over files and read their entire contents. The loop and the reading might be happening in different functions, though.

Definition at line 414 of file fossil-internal.h.

int fsl_cx::flags

Flags, some (or one) of which is runtime-configurable by the client (see fsl_cx_flag_t).

We can get rid of this and add the flags to the cache member along with the rest of them.

Definition at line 427 of file fossil-internal.h.

fsl_buffer fsl_cx::fsScratch

A scratchpad specifically for dealing with filename-related, non-recursive caching.

Definition at line 406 of file fossil-internal.h.

struct { ... } fsl_cx::globs

Holds various glob lists.

int fsl_cx::hasChng

Gets set to true (at some point) if the client has the ticketchnk db table.

Definition at line 608 of file fossil-internal.h.

int fsl_cx::hasChngRid

Gets set to true (at some point) if the client has the ticketchng.rid db field.

Definition at line 613 of file fossil-internal.h.

int fsl_cx::hasCTime

Gets set to true (at some point) if the client has the ticket.tkt_ctime db field.

Definition at line 602 of file fossil-internal.h.

int fsl_cx::hasSetupVfile

Tells us if vfile_selected has been created or not.

Definition at line 359 of file fossil-internal.h.

int fsl_cx::hasTicket

Gets set to true (at some point) if the client has the ticket db table.

Definition at line 597 of file fossil-internal.h.

fsl_deck* fsl_cx::head

Head of the cache list.

All insertions/removals happen at the head.

Definition at line 510 of file fossil-internal.h.

fsl_list fsl_cx::ignore

Holds the "ignore-glob" globs.

Definition at line 560 of file fossil-internal.h.

char fsl_cx::ignoreDephantomizations

Porting artifact.

Not yet used.

Definition at line 457 of file fossil-internal.h.

char fsl_cx::inFinalVerify

Used to tell the content-save internals that a "final verification" (a.k.a.

verify-before-commit) is underway.

Definition at line 491 of file fossil-internal.h.

char fsl_cx::isCrosslinking

True if fsl_mf_crosslink_begin() has been called but fsl_mf_crosslink_end() is still pending.

Definition at line 479 of file fossil-internal.h.

fsl_id_bag fsl_cx::leafCheck

Used during the processing of manifests to keep track of "leaf checks" which need to be done downstream.

Definition at line 533 of file fossil-internal.h.

fsl_uint32_t fsl_cx::limit

TODO: maximum number of entries in the mf linked list.

Definition at line 514 of file fossil-internal.h.

char fsl_cx::markPrivate

Bool flag: whether or not a running commit process should be marked as private.

Definition at line 468 of file fossil-internal.h.

fsl_deck fsl_cx::mf

The deck used for incrementally building certain parts of a checkin.

Definition at line 371 of file fossil-internal.h.

struct { ... } fsl_cx::mf

TODO: a cache of most recently loaded/freed manifests, analog to v1's manifest.c:manifestCache array.

Won't need this until we get to a point where we can rebuild or similar intensive operations.

fsl_id_bag fsl_cx::mfSeen

Used during manifest parsing.

Definition at line 528 of file fossil-internal.h.

fsl_id_t fsl_cx::mtimeManifest

Infrastructure for fsl_mtime_of_manifest_file().

It remembers the previous RID so that it knows when it has to invalidate/rebuild its ancestry cache.

Definition at line 546 of file fossil-internal.h.

fsl_outputer fsl_cx::output

Output channel used by fsl_output() and friends.

Definition at line 377 of file fossil-internal.h.

char* fsl_cx::projectCode

The "project-code" config option.

Definition at line 551 of file fossil-internal.h.

fsl_id_t fsl_cx::rcvId

Record ID of rcvfrom entry during commits.

Definition at line 462 of file fossil-internal.h.

struct { ... } fsl_cx::repo

Holds info directly related to a repo database.

fsl_id_t fsl_cx::rid

The rid of the current checkout.

May be 0 for an empty repo/checkout. Must be negative if not yet known.

Definition at line 315 of file fossil-internal.h.

fsl_buffer fsl_cx::scratch

Optimization: reusable scratchpad for creating/encoding/decoding strings.

Definition at line 400 of file fossil-internal.h.

int fsl_cx::seenManifest

Indicates whether or not this repo has ever seen a manifest.

negative==undetermined, 0==no, positive==yes.

Definition at line 497 of file fossil-internal.h.

fsl_id_bag fsl_cx::selectedIds

Holds a list of "selected files" in the form of vfile.id values.

Definition at line 365 of file fossil-internal.h.

fsl_uint32_t fsl_cx::size

Current number of entries in the mf linked list.

Definition at line 518 of file fossil-internal.h.

struct { ... } fsl_cx::ticket

Ticket-related information.

fsl_id_bag fsl_cx::toVerify

Holds the RID of every record awaiting verification during the verify-at-commit checks.

Definition at line 539 of file fossil-internal.h.

char* fsl_cx::user

The default user name, for operations which need one.

See fsl_cx_user_set().

Definition at line 337 of file fossil-internal.h.

fsl_uuid_str fsl_cx::uuid

The UUID of the current checkout.

Only set if this->rid is positive.

Definition at line 321 of file fossil-internal.h.

char fsl_cx::xlinkClustersOnly

Flag indicating that only cluster control artifacts should be processed by manifest crosslinking.

Definition at line 485 of file fossil-internal.h.

fsl_xlinker_list fsl_cx::xlinkers

List of callbacks for deck crosslinking purposes.

Definition at line 432 of file fossil-internal.h.


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