Working Environments and cross referencing
After a brief note on RAM-based cross referencing, this section concentrates on issues relating to DB-driven cross referencing and Working Environments.
- Regardless of which X-Ref technology you use, mixing X-Ref technologies within a
Working Environment hierarchy does not work. This is because different files are used by
each system, as shown under How the X-Ref subsystems work.
RAM-based cross referencing
Under RAM-based cross referencing, there are no special implications as far as Working Environments are concerned. This is because the X-Ref information files are maintained at project level.
When files are checked out/in they are reparsed, and the procedure for generating X-Ref information as described for this technology under How the X-Ref subsystems work is set in motion when queries are issued. As a result, multiple access is not a problem under RAM-based cross referencing.
DB-driven cross referencing and Working Environments
X-Ref databases are maintained at Working Environment level. Although only one X-Ref database is created per Working Environment, information sharing has to work across Working Environment boundaries. This implies that some sort of mechanism for controlling Read and Write access to database files has to implemented.
X-Ref database access control
Note that "accessing an X-Ref database" effectively means "opening Projects (with symbol information) in a given Working Environment, and thereby accessing the X-Ref database for that Working Environment and higher-level (Shared) Working Environments".
In the following, a number of points relating to database access control are listed, together with examples as they affect team development.
- Write access is absolutely exclusive within a Working Environment.
This means that if an X-Ref database is opened for writing, no other SNIFF+ session can
access the database (neither for reading, nor for writing). In other words, Projects cannot
be opened with symbol information in that Working Environment by other SNiFF+
sessions.
Example:
For day-to-day development work, you will generally open Projects (with symbol
information) in your Private Working Environment. Because you will want any changes
you make to be reflected also in the cross-reference information, you need Write access
to the X-Ref database for that Working Environment. Which is not a problem. A problem
will only arises if and when another SNiFF+ session tries to open Projects (with symbols)
in that same Working Environment.
- Write access is hierarchically absolutely exclusive.
Write access in a higher-level Working Environment (e.g. SSWE) also blocks all (Read
and Write) X-Ref database access in all lower-level Working Environments (e.g. PWEs).
To put it another way, if Projects are opened in a (Shared) Working Environment with
Write access, no lower-level (Private) Working Environment can then access the
database system of the hierarchy in any way. This means that all Working Environments
lower down in the hierarchy are blocked in terms of symbol information.
Example:
What happens when the SSWE needs to be updated? Updating a Working Environment
means, among other things, Write access to its X-Ref database. And Write access is
"hierarchically absolutely exclusive", that is, all Projects open (with symbol information) in
lower-level Working Environments have to be closed. Please refer also to Write access to
an X-Ref database that is already opened in Read mode..
- If a higher-level Working Environment has a Write lock, it is only possible to open Projects
without symbol information (that is, without any X-Ref database access) in lower-level
Working Environments.
- Multiple Read access is possible.
Any number of SNiFF+ sessions can access a given Working Environment's X-Ref
database in Read mode -- as long as it is not already being accessed in Write mode
(see earlier).
Example:
Generally, each user will have Projects opened (with symbols) in Private Working
Environments, that is, with Write access to the PWE's X-Ref database. And all users will
have Read access to the Shared Source Working Environment's X-Ref database.
- Write access to an X-Ref database that is already opened in Read mode.
Not only is Write access hierarchically absolutely exclusive (see earlier), it also allows you
to take priority over existing Read access locks. That is, if an X-Ref database is open in
Read mode by other SNiFF+ sessions, and you attempt a Write access, you are given
two options, a Remote Shutdown option and a Break Lock option.
The Remote Shutdown option saves and closes all Projects in other SNiFF+ sessions
with Read access to the database in question. Note that Remote Shutdown starts
execution after a 30 second delay.
The Break Lock breaks existing locks. This option is not recommended as
inconsistencies are inevitable.
Example:
An unattended nightly update of the SSWE is started, and Write access is therefore
required for the SSWE's X-Ref database. But one or more team members still have active
SNiFF+ sessions with Projects opened in Private Working Environments that access the
SSWE. These open sessions therefore have Read access to the SSWE X-Ref database.
Rather than abort the update, all open files and Projects can be saved and closed using
the Remote Shutdown option. The update then proceeds normally.
- Accessing an X-Ref database that is already opened in Write mode?
You can't. Neither in Read mode, nor in Write mode. At least not without breaking the lock
on the database. This is not to be recommended, and should only be used in exceptional
circumstances.
Example:
None. Do not use the Break Lock option, unless you are certain that this lock is invalid.
Even if SNiFF+ terminates unexpectedly, exit handlers should be able to remove existing
locks.
Where locking information is maintained
Locking information is maintained in a subdirectory of your Working Environments Configuration Directory (you set this in your Preferences) called
.snifflock
. A subdirectory is created for each lockable Working Environment, this subdirectory takes the name of the Working Environment for which the locking information is maintained. All current Read access locks are stored directly in this subdirectory. Each of these subdirectories can have another subdirectory called
lock
. Any existing Write access lock on the Working Environment is stored in the
lock
subdirectory.
Lock file names have the following syntax:
lock.
machinename.
PID
If an attempt is made to access locked databases, files are created called
try.machinename.
PID
These files are used by SNiFF+ to identify requests for X-Ref database access.
Maintenance of X-Ref databases
If, for some reason, databases become corrupt, SNiFF+ may be able to repair them. If the databases are irreparably damaged, they can be recreated from scratch by deleting the corrupt database files (see also Location of generated X-Ref information) and issuing a Force Reparse command.
The information in the X-Ref database is cumulative, that is X-Ref information for every project ever opened in a given Working Environment is stored in that Working Environment's database. The X-Ref information for any given project will only be removed from the database when the Project is deleted using the Delete Project command.
Synchronizing Working Environments
The correct order for updating/synchronizing Working Environments should always be
maintained to avoid inconsistencies. This is
- Shared Source Working Environment (SSWE)
- Shared Object Working Environment (SOWE)
- Private Working Environment (PWE)
Again: Whenever a higher-level Working Environment (e.g. SSWE) is updated, all lower-
level Working Environments (e.g. PWEs) accessing it should (must) be subsequently
updated.
This holds especially for DB-driven cross referencing. Apart from all other possible
inconsistencies caused by out-of-sync Working Environments, cross reference
information will also be inconsistent because, for performance reasons, internal database
objects are shared among Working Environments.