1.0 Introduction
Starting with Giocoso version 2.01, locks are placed whenever Giocoso is used to play music or scan music files for inclusion in a database. The lock prevents a second music-playing or music-scanning session being launched whilst the first is still running -because to do so means files needed by the first session would be over-written by the new session, resulting in both sessions getting completely confused!
Prior to version 2.01, for example, launching a second music-playing Giocoso session would cause the music already playing to be immediately halted, but the second session wouldn't then start playing music either. Result: total silence! Similarly, before version 2.01, if you launched a new database refresh process whilst the first was already running, the result would be that your music database would end up completely empty (of recordings, not plays): neither session would complete correctly. The new locks prevent this sort of 'collision'.
The "locks" are really just temporary files, stored within the $HOME/.local/share/giocoso folder. If you launch a new Giocoso session and it sees either of the play or scanning lock files present in that folder, it will immediately quit, with a message such as this one:
Note that you can launch second, simultaneous Giocoso sessions if they are not going to play music or scan music files. Where no possibility of conflict arises, no issue of simultaneity arises either. Thus, for example, if you launch a second session of Giocoso with the command "giocoso --autostop", that's merely asking Giocoso to send a message to the playing session to quit playing further music once the current play completes. There is thus no attempt by this second session to play music itself, so the existence or non-existence of the 'play lock' is irrelevant to it.
2.0 Orphan Locks
Giocoso automatically removes the temporary files which act as play and scanning locks whenever it completes a play session or a database refresh. If you launch Giocoso with --selections=9, for example, then the lock is placed; nine recordings are played; and then the lock is removed at the conclusion of the ninth recording.
If anything prevents Giocoso from concluding its play cycle or its database refresh in a normal way, however, there is a possibility that either lock file might be 'left behind' on disk without Giocoso having an opportunity to clear it by itself. If, for example, your PC crashes mid-play, or you were to run a 'kill -9 giocoso' command for some reason: either would mean Giocoso dying before getting a chance to clean up its locks. The problem then becomes when you next try to launch Giocoso to play music or refresh a database: the new Giocoso session will spot the locks left over from the previous, now-dead, session and refuse to play or scan music.
When a lock file is left behind on disk in this way, we call them 'orphan locks' -because the parent session that spawned them has died, without tidying them up.
Orphan locks prevent all further attempts to play music or perform database refreshes, which is obviously a bit of a problem!
The manual fix for an orphan lock, whether an orphan play lock or an orphan scan lock, is to delete the appropriate file off disk manually. This can be done in a terminal or using your distro's file manager: just navigate to $HOME/.local/share/giocoso and delete any files called:
- playlock
- scanlock
The files do not have an extension, neither do they contain any data.
Do not delete a scan or play lock file manually unless you are absolutely certain that no other Giocoso session is refreshing its database or playing music. Removing a lock file that's actually needed to prevent 'collision' will, obviously, cause collision ...and that means database corruption or playback interruption. However, there is nothing stopping you from removing lock files of either sort at any time of your choosing: if you thereby cause the problems the locks were intended to prevent, that's down to you!
3.0 Controlled Fixing of Orphan Locks
Having to open your file manager to fix an orphan lock is a bit of a clumsy, heavy-handed way of dealing with orphan locks (though undeniably effective!) Therefore, starting with Giocoso version 2.01, you can launch a new Giocoso session with the new runtime parameters --unlock or --descan to achieve the same sort of result without major effort on your part. The --unlock parameter triggers the removal of the play lock; the --descan parameter triggers the removal of the database music refresh/scanning lock. A simple confirmation message will be displayed in either case to tell you the relevant lock file has been removed.
In Giocoso version 2.01, a new simplified menu interface was introduced to make running and managing Giocoso easier. Option 13 from the main menu gives access to an 'Administrative tasks' sub-menu:
Option 3 of this sub-menu removes the play lock (it effectively runs the --unlock parameter under the hood); Option 4 removes the database scan/refresh lock (by effectively running the --descan parameter behind the scenes).
4.0 Conclusion
Summing up:
- Play and Scan locks were introduced in Giocoso version 2.01 to prevent 'collisions' between simultaneously-running Giocoso sessions, resulting in poor outcomes for music playback or database refreshes
- Giocoso normally cleans up any play or scan locks when they are no longer required by itself
- Program or OS crashes, or deliberate killing of Giocoso sessions by OS administrative action, will leave behind the Play or Scan locks, before Giocoso has a chance to clean them up by itself, thereby creating 'orphan locks'
- The presence of an orphan play lock will prevent all future attempts to play music with Giocoso; an orphan scan lock will, likewise, prevent any future attempt to refresh your music database
- If you are ever faced with the problem of orphan locks, you can fix them by (1) manually deleting the playlock or scanlock file yourself; (2) running a new Giocoso session with the runtime parameters --unlock or --descan (one at a time, please!); or (3) running Giocoso from the simplified menu interface and taking options 13 -> 3 or 13 -> 4
- Whilst nothing will stop you from removing a play or scan lock at any time, doing so when the lock is actually needed to prevent collisions is likely to result in the creation of the sort of problems the locks were invented to prevent in the first place. Removal of the locks is therefore not recommended unless you are facing "Err0024 - A database create/refresh operation already appears to be in progress." or "Err0026 - An instance of Giocoso playing music already exists" error messages.