[mythtv-commits] mythtv commit: r23012 - in trunk/mythtv by cpinkham

mythtv at cvs.mythtv.org mythtv at cvs.mythtv.org
Mon Dec 28 05:28:24 UTC 2009

      Author: cpinkham
        Date: 2009-12-28 05:28:23 +0000 (Mon, 28 Dec 2009)
New Revision: 23012
   Changeset: http://svn.mythtv.org/trac/changeset/23012






This commit creates an event-driven notification system to trigger
user-specified commands when certain events occur in MythTV.

A new MythSystemEventHandler class is instantiated when mythbackend,
mythfrontend, and mythjobqueue are started.  This allows any frontend,
backend, or JobQueue server to process system event messages and run
the corresponding user-specified command.

The current list of events which are handled are:

Recording pending
Recording started
Recording finished
Recording deleted
Recording expired
Playback started
Playback stopped
Playback paused
Playback unpaused
Playback program changed
Master backend started
Master backend shutdown
Client connected to master backend
Client disconnected from master backend
Slave backend connected to master
Slave backend disconnected from master
Network Control client connected
Network Control client disconnected
mythfilldatabase ran
Scheduler ran
Settings cache cleared

Along with the above predefined system events, the user can also configure
up to 10 user-generated keystroke events and associate them with a keypress
as normal keys are configured.

MythTV System Event handler commands are configured on a per server basis.
A given System Event may have a command to be run on one backend but not
on another, or only on a particular frontend.  System Event handler commands
may be configured via either mythtv-setup or mythfrontend's setup area.
When a System Event fires, a handler command is run on any system that has
the handler command configured for that System Event.  This applies even for
the user-generated keystroke events.  It is up to the user's script to
determine whether to act on the event or not.  For instance, when the
"Playback started" event is fired, any frontend that has a handler command
configured for this event will run the handler command, it is up to the
handler script to determine whether to act on the event depending on
whether it is concerned that playback started on the particular given host.
This functionality allows the user to control where to run events and also
allows the user to generate events on one or more frontends via keystrokes
and have those keystrokes trigger a command or script to run on a particular
backend.  This could be useful for maniupulating hardware such as a
multi-DVD changer connected to a remote backend.

System Event commands can be used for numerous things, a couple examples
include the above-mentioned remote DVD changer, turning room lights on/off
when playback stops/starts, and emailing the latest schedule whenever the
scheduler completes a run.

System Events may be sent via the command line using a new command line
option called --systemevent to mythbackend.  System Event handler commands
are stored in the normal MythTV settings table.  This means that the user
can create and fire their own System Event commands via a combination of
the -O settings override option and the --systemevent option.  To setup a
handler for a user-created event, run mythbackend similar to this:

    mythbackend -O EventCmdUser1=/usr/local/bin/myth_event_user_01.sh

to send the User1 System Event on the same host or a remote host:

    mythbackend --systemevent USER_1

Using this functionality, users can for instance send their own event when
a User Job runs or completes and have the event trigger a command to be
run on a remote backend or frontend.

System Event handler commands can utilize the same %MATCH% type variable
substitution as MythJobQueue handler commands.  Additional variable
substitutions are:

CARDID - cardid a recording is being made on
SECS   - seconds until a recording starts
SENDER - hostname of system sending the event

All System Event handler commands are run in the background in the global
QThreadPool.  The event handler thread releases the thread so that the
thread does not count against the max thread count in the pool.  This is
done so that long-running handler commands do not use all threads and
prevent other shorter-running handler commands from executing.

System Event handler commands are run only once for all processes running
on a given host.  If a host has a handler command configured for a specific
event and both mythfrontend and mythbackend are running on that host, the
handler command will be run only once.  Which process actually runs the
handler command is unspecified in the case of a slave backend and a
frontend process.  The first process connection to be found by the master
backend will handle the command.  In the case of a master backend also
running a frontend process, the master backend will always handle the
event and run the command, the frontend process will never see the event.

More information about the mythtv-commits mailing list