/*
 * Copyright 1991-1999, Be Incorporated.
 * Copyright (c) 1999-2000, Eric Moon.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions, and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


// LoggingConsumer.cpp

#include "LoggingConsumer.h"
#include "LogWriter.h"
#include <media/MediaRoster.h>
#include <media/TimeSource.h>
#include <media/ParameterWeb.h>
#include <media/Buffer.h>
#include <kernel/OS.h>
#include <stdio.h>
#include <string.h>

// e.moon [11jun99]
#include <Catalog.h>
#include <Debug.h>

#undef B_TRANSLATION_CONTEXT
#define B_TRANSLATION_CONTEXT "CortexAddOnsLoggingConsumer"

// id's of the node's BParameters
const int32 INPUT_NULL_PARAM = 1;
const int32 LATENCY_PARAM = 2;
const int32 OUTPUT_NULL_PARAM = 3;
const int32 CPU_NULL_PARAM = 11;
const int32 CPU_SPIN_PARAM = 12;
const int32 PRIO_NULL_PARAM = 21;
const int32 PRIORITY_PARAM = 22;

// build the LoggingConsumer's BParameterWeb
static BParameterWeb* build_parameter_web()
{
        BParameterWeb* web = new BParameterWeb;

        BParameterGroup* mainGroup = web->MakeGroup(
                B_TRANSLATE("LoggingConsumer parameters"));
        BParameterGroup* group = mainGroup->MakeGroup(
                B_TRANSLATE("Latency control"));
        BParameter* nullParam = group->MakeNullParameter(INPUT_NULL_PARAM,
                B_MEDIA_NO_TYPE, B_TRANSLATE("Latency"), B_GENERIC);
        BParameter* latencyParam = group->MakeContinuousParameter(LATENCY_PARAM,
                B_MEDIA_NO_TYPE, "", B_GAIN, "ms", 5, 100, 5);
        nullParam->AddOutput(latencyParam);
        latencyParam->AddInput(nullParam);

        group = mainGroup->MakeGroup(B_TRANSLATE("CPU percentage"));
        nullParam = group->MakeNullParameter(CPU_NULL_PARAM, B_MEDIA_NO_TYPE,
                B_TRANSLATE("CPU spin percentage"), B_GENERIC);
        BContinuousParameter* cpuParam = group->MakeContinuousParameter(
                CPU_SPIN_PARAM, B_MEDIA_NO_TYPE, "",
                B_GAIN, B_TRANSLATE("percent"), 5, 80, 5);
        nullParam->AddOutput(cpuParam);
        cpuParam->AddInput(nullParam);

        group = mainGroup->MakeGroup(B_TRANSLATE("Priority"));
        nullParam = group->MakeNullParameter(PRIO_NULL_PARAM, B_MEDIA_NO_TYPE,
                B_TRANSLATE("Thread priority"), B_GENERIC);
        BDiscreteParameter* prioParam = group->MakeDiscreteParameter(PRIORITY_PARAM,
                B_MEDIA_NO_TYPE, "", B_GENERIC);
        prioParam->AddItem(5, "B_LOW_PRIORITY");
        prioParam->AddItem(10, "B_NORMAL_PRIORITY");
        prioParam->AddItem(15, "B_DISPLAY_PRIORITY");
        prioParam->AddItem(20, "B_URGENT_DISPLAY_PRIORITY");
        prioParam->AddItem(100, "B_REAL_TIME_DISPLAY_PRIORITY");
        prioParam->AddItem(110, "B_URGENT_PRIORITY");
        prioParam->AddItem(120, "B_REAL_TIME_PRIORITY");

        return web;
}

// --------------------
// LoggingConsumer class implementation
LoggingConsumer::LoggingConsumer(
        const entry_ref& logFile,
        BMediaAddOn* pAddOn)

        :       BMediaNode("LoggingConsumer"),
                BBufferConsumer(B_MEDIA_UNKNOWN_TYPE),
                BControllable(),
                BMediaEventLooper(),
                mLogRef(logFile),
                mWeb(NULL),
                mLateBuffers(0),
                mLatency(50 * 1000),            // default to 50 milliseconds
                mSpinPercentage(0.10),          // default to spinning 10% of total latency
                mPriority(B_URGENT_DISPLAY_PRIORITY),           // !!! testing; will be B_REAL_TIME_PRIORITY for release
                mLastLatencyChange(0),
                mLastSpinChange(0),
                mLastPrioChange(0),
                m_pAddOn(pAddOn)
{
        // spin off the logging thread
        mLogger = new LogWriter(logFile);

        // parameter-web init moved to NodeRegistered()
        // e.moon [11jun99]
}

LoggingConsumer::~LoggingConsumer()
{
        PRINT(("~LoggingConsumer()\n"));
        BMediaEventLooper::Quit();
// ahem:
// "Once you've called BControllable::SetParameterWeb(), the node takes
//  responsibility for the parameter web object and you shouldn't delete it. "
//      SetParameterWeb(NULL);
//      delete mWeb;

        // delete the logging thread only after the looper thread has quit, otherwise there's
        // a potential race condition with the looper thread trying to write to the now-
        // deleted log
        delete mLogger;
}

//
// Log message filtering control
//

void
LoggingConsumer::SetEnabled(log_what what, bool enable)
{
        mLogger->SetEnabled(what, enable);
}

void
LoggingConsumer::EnableAllMessages()
{
        mLogger->EnableAllMessages();
}

void
LoggingConsumer::DisableAllMessages()
{
        mLogger->DisableAllMessages();
}

//
// BMediaNode methods
//


BMediaAddOn*
LoggingConsumer::AddOn(int32 *internal_id) const
{
        PRINT(("~LoggingConsumer::AddOn()\n"));
        // e.moon [11jun99]
        if(m_pAddOn) {
                *internal_id = 0;
                return m_pAddOn;
        } else
                return NULL;
}

void
LoggingConsumer::SetRunMode(run_mode mode)
{
        // !!! Need to handle offline mode etc. properly!
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_SET_RUN_MODE, logMsg);

        BMediaEventLooper::SetRunMode(mode);
}

void
LoggingConsumer::Preroll()
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_PREROLL, logMsg);

        BMediaEventLooper::Preroll();
}

void
LoggingConsumer::SetTimeSource(BTimeSource* time_source)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_SET_TIME_SOURCE, logMsg);

        BMediaNode::SetTimeSource(time_source);
}

status_t
LoggingConsumer::RequestCompleted(const media_request_info &info)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_REQUEST_COMPLETED, logMsg);

        return BMediaNode::RequestCompleted(info);
}

// e.moon [11jun99; testing add-on]
status_t
LoggingConsumer::DeleteHook(BMediaNode* pNode) {
        PRINT(("LoggingConsumer::DeleteHook(%p)\n", pNode));
        return BBufferConsumer::DeleteHook(pNode);
//      ASSERT(pNode == this);
//      delete this;
//      return B_OK;
}

//
// BControllable methods
//

status_t
LoggingConsumer::GetParameterValue(int32 id, bigtime_t* last_change, void* value, size_t* ioSize)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        logMsg.param.id = id;
        mLogger->Log(LOG_GET_PARAM_VALUE, logMsg);

        // return an error if the caller hasn't reserved enough space for the parameter data.
        // we know that all of our parameters fit in a float or int32 (4 bytes), so we can just
        // check for it once here, instead of on a per-parameter basis
        if (*ioSize < sizeof(float)) return B_ERROR;

        // write out the designated parameter data
        switch (id)
        {
        case LATENCY_PARAM:
                *last_change = mLastLatencyChange;
                *((float*) value) = mLatency / 1000;            // the BParameter reads milliseconds, not microseconds
                *ioSize = sizeof(float);
                break;

        case CPU_SPIN_PARAM:
                *last_change = mLastSpinChange;
                *((float*) value) = mSpinPercentage;
                *ioSize = sizeof(float);
                break;

        case PRIORITY_PARAM:
                *last_change = mLastPrioChange;
                *((int32*) value) = mPriority;
                *ioSize = sizeof(int32);
                break;

        default:
                return B_ERROR;
        }

        return B_OK;
}

void
LoggingConsumer::SetParameterValue(int32 id, bigtime_t performance_time, const void* value, size_t size)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        logMsg.param.id = id;
        mLogger->Log(LOG_SET_PARAM_VALUE, logMsg);

        // if it's one of our parameters, enqueue a "set parameter" event for handling at the appropriate time
        switch (id)
        {
        case LATENCY_PARAM:
        case CPU_SPIN_PARAM:
        case PRIORITY_PARAM:
                {
                        // !!! Change from B_USER_EVENT to B_SET_PARAMETER once it's defined
                        media_timed_event event(performance_time, BTimedEventQueue::B_USER_EVENT,
                                (void*) value, BTimedEventQueue::B_NO_CLEANUP, size, id, NULL);
                        EventQueue()->AddEvent(event);
                }
                break;

        default:                // do nothing for other parameter IDs
                break;
        }
        return;
}

//
// BBufferConsumer methods
//

status_t
LoggingConsumer::HandleMessage(int32 message, const void *data, size_t size)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_HANDLE_MESSAGE, logMsg);

        // try each of our superclasses to handle the message
        status_t err;
        err = BControllable::HandleMessage(message, data, size);
        if (err) err = BBufferConsumer::HandleMessage(message, data, size);
        if (err) err = BMediaNode::HandleMessage(message, data, size);
        return err;
}

// all of these next methods are pure virtual in BBufferConsumer

status_t
LoggingConsumer::AcceptFormat(const media_destination& dest, media_format* format)
{
        char formatStr[256];
        string_for_format(*format, formatStr, 255);
        PRINT(("LoggingConsumer::AcceptFormat:\n\tformat %s\n", formatStr));

        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_ACCEPT_FORMAT, logMsg);

        // return an error if this isn't really our one input's destination
        if (dest != mInput.destination) return B_MEDIA_BAD_DESTINATION;

        // the destination given really is our input, and we accept any kind of media data,
        // so now we just confirm that we can handle whatever the producer asked for.
        return B_OK;
}

status_t
LoggingConsumer::GetNextInput(int32* cookie, media_input* out_input)
{
        // we have a single hardcoded input that can accept any kind of media data
        if (0 == *cookie)
        {
                mInput.format.type = B_MEDIA_UNKNOWN_TYPE;              // accept any format

                *out_input = mInput;
                *cookie = 1;
                return B_OK;
        }
        else return B_BAD_INDEX;
}

void
LoggingConsumer::DisposeInputCookie(int32 /*cookie*/ )
{
        // we don't use any kind of state or extra storage for iterating over our
        // inputs, so we don't have to do any special disposal of input cookies.
}

void
LoggingConsumer::BufferReceived(BBuffer* buffer)
{
        bigtime_t bufferStart = buffer->Header()->start_time;
        bigtime_t now = TimeSource()->Now();
        bigtime_t how_early = bufferStart - EventLatency() - SchedulingLatency() - now;

        log_message logMsg;
        logMsg.now = now;
        logMsg.buffer_data.start_time = bufferStart;
        logMsg.buffer_data.offset = how_early;
        logMsg.buffer_data.size_available = buffer->SizeAvailable();
        logMsg.buffer_data.size_used = buffer->SizeUsed();
        logMsg.buffer_data.flags = buffer->Flags();
        logMsg.buffer_data.id = buffer->ID();
        logMsg.buffer_data.type = buffer->Type();
        mLogger->Log(LOG_BUFFER_RECEIVED, logMsg);

        // There's a special case here with handling B_MEDIA_PARAMETERS buffers.
        // These contain sets of parameter value changes, with their own performance
        // times embedded in the buffers.  So, we want to dispatch those parameter
        // changes as their own events rather than pushing this buffer on the queue to
        // be handled later.
        if (B_MEDIA_PARAMETERS == buffer->Header()->type)
        {
                ApplyParameterData(buffer->Data(), buffer->SizeUsed());
                buffer->Recycle();
        }
        else            // ahh, it's a regular media buffer, so push it on the event queue
        {
                status_t err;
                media_timed_event event(buffer->Header()->start_time, BTimedEventQueue::B_HANDLE_BUFFER,
                        buffer, BTimedEventQueue::B_RECYCLE_BUFFER);
                err = EventQueue()->AddEvent(event);

                // HandleEvent() will recycle the buffer.  However, if we incurred an error trying to
                // put the event into the queue, we have to recycle it ourselves, since HandleEvent()
                // will never see the buffer in that case.
                if (err) buffer->Recycle();
        }
}

void
LoggingConsumer::ProducerDataStatus(const media_destination& for_whom, int32 status, bigtime_t at_performance_time)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        logMsg.data_status.status = status;
        mLogger->Log(LOG_PRODUCER_DATA_STATUS, logMsg);

        if (for_whom == mInput.destination)
        {
                media_timed_event event(at_performance_time, BTimedEventQueue::B_DATA_STATUS,
                        &mInput, BTimedEventQueue::B_NO_CLEANUP, status, 0, NULL);
                EventQueue()->AddEvent(event);
        }
}

status_t
LoggingConsumer::GetLatencyFor(const media_destination& for_whom, bigtime_t* out_latency, media_node_id* out_timesource)
{
        // make sure this is one of my valid inputs
        if (for_whom != mInput.destination) return B_MEDIA_BAD_DESTINATION;

        // report internal latency + downstream latency here, NOT including scheduling latency.
        // we're a final consumer (no outputs), so we have no downstream latency.
        *out_latency = mLatency;
        *out_timesource = TimeSource()->ID();
        return B_OK;
}

status_t
LoggingConsumer::Connected(
        const media_source& producer,
        const media_destination& where,
        const media_format& with_format,
        media_input* out_input)
{

        char formatStr[256];
        string_for_format(with_format, formatStr, 255);
        PRINT(("LoggingConsumer::Connected:\n\tformat %s\n", formatStr));
        string_for_format(mInput.format, formatStr, 255);
        PRINT(("\tinput format %s\n", formatStr));

        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_CONNECTED, logMsg);

        if (where != mInput.destination) return B_MEDIA_BAD_DESTINATION;

        // calculate my latency here, because it may depend on buffer sizes/durations, then
        // tell the BMediaEventLooper how early we need to get the buffers
        SetEventLatency(mLatency);

        // record useful information about the connection, and return success
        // * e.moon [14jun99]: stores format
        mInput.format = with_format;
        mInput.source = producer;
        *out_input = mInput;
        return B_OK;
}

void
LoggingConsumer::Disconnected(
        const media_source& producer,
        const media_destination& where)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_DISCONNECTED, logMsg);

        // wipe out our input record
        mInput = media_input();
}

status_t
LoggingConsumer::FormatChanged(
        const media_source& producer,
        const media_destination& consumer,
        int32 change_tag,
        const media_format& format)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_FORMAT_CHANGED, logMsg);

        return B_OK;
}

status_t
LoggingConsumer::SeekTagRequested(
        const media_destination& destination,
        bigtime_t in_target_time,
        uint32 in_flags,
        media_seek_tag* out_seek_tag,
        bigtime_t* out_tagged_time,
        uint32* out_flags)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_SEEK_TAG, logMsg);

        return B_OK;
}

//
// BMediaEventLooper virtual methods
//

void
LoggingConsumer::NodeRegistered()
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_REGISTERED, logMsg);

        // publish our parameter web
        mWeb = build_parameter_web();
        SetParameterWeb(mWeb);

        // Set our priority and start the BMediaEventLooper's thread
        SetPriority(mPriority);
        Run();

        // Initialize as much of our input as we can, now that the Media Kit really "knows" about us
        mInput.destination.port = ControlPort();
        mInput.destination.id = 0;
        mInput.node = Node();
        strcpy(mInput.name, B_TRANSLATE("Logged input"));
}

void
LoggingConsumer::Start(bigtime_t performance_time)
{
        PRINT(("LoggingConsumer::Start(%" B_PRIdBIGTIME "): now %" B_PRIdBIGTIME "\n",
                performance_time, TimeSource()->Now()));

        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_START, logMsg);

        BMediaEventLooper::Start(performance_time);
}

void
LoggingConsumer::Stop(bigtime_t performance_time, bool immediate)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_STOP, logMsg);

        BMediaEventLooper::Stop(performance_time, immediate);
}

void
LoggingConsumer::Seek(bigtime_t media_time, bigtime_t performance_time)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_SEEK, logMsg);

        BMediaEventLooper::Seek(media_time, performance_time);
}

void
LoggingConsumer::TimeWarp(bigtime_t at_real_time, bigtime_t to_performance_time)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_TIMEWARP, logMsg);

        BMediaEventLooper::TimeWarp(at_real_time, to_performance_time);
}

void
LoggingConsumer::HandleEvent(const media_timed_event *event, bigtime_t /* lateness */, bool /* realTimeEvent */)
{
        log_message logMsg;
        logMsg.now = TimeSource()->Now();
        mLogger->Log(LOG_HANDLE_EVENT, logMsg);

        switch (event->type)
        {
        case BTimedEventQueue::B_HANDLE_BUFFER:
                {
                        BBuffer* buffer = const_cast<BBuffer*>((BBuffer*) event->pointer);
                        if (buffer)
                        {
                                media_header* hdr = buffer->Header();
                                if (hdr->destination == mInput.destination.id)
                                {
                                        bigtime_t now = TimeSource()->Now();
                                        bigtime_t perf_time = hdr->start_time;

                                        // the how_early calculated here doesn't include scheduling latency because
                                        // we've already been scheduled to handle the buffer
                                        bigtime_t how_early = perf_time - mLatency - now;

                                        // logMsg.now is already set
                                        logMsg.buffer_data.start_time = perf_time;
                                        logMsg.buffer_data.offset = how_early;
                                        mLogger->Log(LOG_BUFFER_HANDLED, logMsg);

                                        // if the buffer is late, we ignore it and report the fact to the producer
                                        // who sent it to us
                                        if (how_early < 0)
                                        {
                                                mLateBuffers++;
                                                NotifyLateProducer(mInput.source, -how_early, perf_time);
                                        }
                                        else
                                        {
                                                // burn some percentage of our stated latency in CPU time (controlled by
                                                // a BParameter).  this simulates a user-configurable amount of CPU cost
                                                // associated with the consumer.
                                                bigtime_t spin_start = ::system_time();
                                                bigtime_t spin_now = spin_start;
                                                bigtime_t usecToSpin = bigtime_t(mSpinPercentage / 100.0 * mLatency);
                                                while (spin_now - spin_start < usecToSpin)
                                                {
                                                        for (long k = 0; k < 1000000; k++) { /* intentionally blank */ }
                                                        spin_now = ::system_time();
                                                }
                                        }

                                        // we're done "processing the buffer;" now we recycle it and return to the loop
                                        buffer->Recycle();
                                }
                                else
                                {
                                        //fprintf(stderr, "* Woah!  Got a buffer for a different destination!\n");
                                }
                        }
                }
                break;

        // !!! change to B_PARAMETER as soon as it's available

        // +++++ e.moon [16jun99]
        // !!! this can't be right: the parameter value is accessed by the pointer
        //     originally passed to SetParameterValue().  there's no guarantee that
        //     value's still valid, is there?

        case BTimedEventQueue::B_USER_EVENT:
                {
                        size_t dataSize = size_t(event->data);
                        int32 param = int32(event->bigdata);
                        logMsg.param.id = param;

                        // handle the message if there's sufficient data provided.  we only check against
                        // sizeof(float) because all of our parameters happen to be 4 bytes.  if various
                        // parameters took different amounts of data, we'd check the size on a per-parameter
                        // basis.
                        if (dataSize >= sizeof(float)) switch (param)
                        {
                        case LATENCY_PARAM:
                                {
                                        float value = *((float*) event->pointer);
                                        mLatency = bigtime_t(value* 1000);
                                        mLastLatencyChange = logMsg.now;

                                        // my latency just changed, so reconfigure the BMediaEventLooper
                                        // to give me my events at the proper time
                                        SetEventLatency(mLatency);

                                        // tell the producer that my latency changed, and broadcast a message
                                        // about the parameter change to any applications that may be looking
                                        // for it through the BMediaRoster::StartWatching() mechanism.
                                        //
                                        // if we had more than one input, we'd need to tell *all* producers about
                                        // the change in our latency.
                                        SendLatencyChange(mInput.source, mInput.destination, EventLatency() + SchedulingLatency());
                                        BroadcastNewParameterValue(logMsg.now, param, &value, sizeof(value));

                                        // log the new latency value, for recordkeeping
                                        logMsg.param.value = value;
                                        mLogger->Log(LOG_SET_PARAM_HANDLED, logMsg);
                                }
                                break;

                        case CPU_SPIN_PARAM:
                                {
                                        float value = *((float*) event->pointer);
                                        mSpinPercentage = value;
                                        mLastSpinChange = logMsg.now;
                                        BroadcastNewParameterValue(logMsg.now, param, &value, sizeof(value));
                                        logMsg.param.value = value;
                                        mLogger->Log(LOG_SET_PARAM_HANDLED, logMsg);
                                }
                                break;

                        case PRIORITY_PARAM:
                                {
                                        mPriority = *((int32*) event->pointer);
                                        // DO NOT use ::set_thead_priority() to directly alter the node's control
                                        // thread priority.  BMediaEventLooper tracks the priority itself and recalculates
                                        // the node's scheduling latency whenever SetPriority() is called.  This is VERY
                                        // important for correct functioning of a node chain.  You should *only* alter a
                                        // BMediaEventLooper's priority by calling its SetPriority() method.
                                        SetPriority(mPriority);

                                        mLastPrioChange = logMsg.now;
                                        BroadcastNewParameterValue(logMsg.now, param, &mPriority, sizeof(mPriority));
                                        logMsg.param.value = (float) mPriority;
                                        mLogger->Log(LOG_SET_PARAM_HANDLED, logMsg);
                                }
                                break;

                        // log the fact that we "handled" a "set parameter" event for a
                        // nonexistent parameter
                        default:
                                mLogger->Log(LOG_INVALID_PARAM_HANDLED, logMsg);
                                break;
                        }
                }
                break;

        case BTimedEventQueue::B_START:
                // okay, let's go!
                mLogger->Log(LOG_START_HANDLED, logMsg);
                break;

        case BTimedEventQueue::B_STOP:
                mLogger->Log(LOG_STOP_HANDLED, logMsg);
                // stopping implies not handling any more buffers.  So, we flush all pending
                // buffers out of the event queue before returning to the event loop.
                EventQueue()->FlushEvents(0, BTimedEventQueue::B_ALWAYS, true, BTimedEventQueue::B_HANDLE_BUFFER);
                break;

        case BTimedEventQueue::B_SEEK:
                // seeking the log doesn't make any sense, so we just log that we handled the seek
                // and return without doing anything else
                mLogger->Log(LOG_SEEK_HANDLED, logMsg);
                break;

        case BTimedEventQueue::B_WARP:
                // similarly, time warps aren't meaningful to the logger, so just record it and return
                mLogger->Log(LOG_WARP_HANDLED, logMsg);
                break;

        case BTimedEventQueue::B_DATA_STATUS:
                // we really don't care about the producer's data status, but this is where
                // we'd do something about it if we did.
                logMsg.data_status.status = event->data;
                mLogger->Log(LOG_DATA_STATUS_HANDLED, logMsg);
                break;

        default:
                // hmm, someone enqueued a message that we don't understand.  log and ignore it.
                logMsg.unknown.what = event->type;
                mLogger->Log(LOG_HANDLE_UNKNOWN, logMsg);
                break;
        }
}