PendingTracks Class Reference

#include <PendingTracks.h>

Inheritance diagram for PendingTracks:

Collaboration diagram for PendingTracks:

Public Types
using	Updater = std::function< void(Track &dest, const Track &src)>
Public Types inherited from Observer::Publisher< TrackListEvent >
using	message_type = TrackListEvent
using	CallbackReturn = std::conditional_t< true, void, bool >
using	Callback = std::function< CallbackReturn(const TrackListEvent &) >
	Type of functions that can be connected to the Publisher. More...

Public Member Functions
	PendingTracks (AudacityProject &project)
	PendingTracks (const PendingTracks &)=delete
PendingTracks &	operator= (const PendingTracks &)=delete
	~PendingTracks ()
void	RegisterPendingNewTracks (TrackList &&list)
Channel &	SubstitutePendingChangedChannel (Channel &channel) const
const Channel &	SubstitutePendingChangedChannel (const Channel &channel) const
Track &	SubstitutePendingChangedTrack (Track &track) const
const Track &	SubstitutePendingChangedTrack (const Track &track) const
const Channel &	SubstituteOriginalChannel (const Channel &channel) const
const Track &	SubstituteOriginalTrack (const Track &track) const
Track *	RegisterPendingChangedTrack (Updater updater, Track *src)
	Start a deferred update of the project. More...
void	UpdatePendingTracks ()
void	ClearPendingTracks (std::vector< std::shared_ptr< Track > > *pAdded=nullptr)
	Forget pending track additions and changes;. More...
bool	ApplyPendingTracks ()
	Change the state of the project. More...
bool	HasPendingTracks () const
Public Member Functions inherited from ClientData::Base
virtual	~Base ()
Public Member Functions inherited from Observer::Publisher< TrackListEvent >
	Publisher (ExceptionPolicy *pPolicy=nullptr, Alloc a={})
	Constructor supporting type-erased custom allocation/deletion. More...
	Publisher (Publisher &&)=default
Publisher &	operator= (Publisher &&)=default
Subscription	Subscribe (Callback callback)
	Connect a callback to the Publisher; later-connected are called earlier. More...
Subscription	Subscribe (Object &obj, Return(Object::*callback)(Args...))
	Overload of Subscribe takes an object and pointer-to-member-function. More...

Static Public Member Functions
static PendingTracks &	Get (AudacityProject &project)
static const PendingTracks &	Get (const AudacityProject &project)

Private Member Functions
std::pair< Track *, Channel * >	DoSubstitutePendingChangedChannel (Track &track, size_t channelIndex) const
std::pair< const Track *, const Channel * >	DoSubstituteOriginalChannel (const Track &track, size_t channelIndex) const

Private Attributes
TrackList &	mTracks
Observer::Subscription	mTrackListSubscription
std::vector< Updater >	mUpdaters
std::shared_ptr< TrackList >	mPendingUpdates

Additional Inherited Members
Static Public Attributes inherited from Observer::Publisher< TrackListEvent >
static constexpr bool	notifies_all
Protected Member Functions inherited from Observer::Publisher< TrackListEvent >
CallbackReturn	Publish (const TrackListEvent &message)
	Send a message to connected callbacks. More...

Detailed Description

Definition at line 23 of file PendingTracks.h.

Member Typedef Documentation

Updater

using PendingTracks::Updater = std::function<void(Track &dest, const Track &src)>

The tracks supplied to this function will have the same number of channels

Definition at line 67 of file PendingTracks.h.

Constructor & Destructor Documentation

PendingTracks() [1/2]

PendingTracks::PendingTracks ( AudacityProject &  project )

explicit

Definition at line 31 of file PendingTracks.cpp.

   : mTracks{ TrackList::Get(project) }
   , mTrackListSubscription { mTracks.Subscribe(
      [this](const TrackListEvent &event){
         switch (event.mType) {
         case TrackListEvent::PERMUTED:
         case TrackListEvent::RESIZING:
         case TrackListEvent::ADDITION:
         case TrackListEvent::DELETION:
            UpdatePendingTracks();
            break;
         default:
            break;
         }
         // Pass along to downstream listeners
         Publish(event);
   })}
   , mPendingUpdates{ TrackList::Temporary(mTracks.GetOwner()) }
{}

References TrackListEvent::ADDITION, TrackListEvent::DELETION, TrackListEvent::PERMUTED, Observer::Publisher< TrackListEvent >::Publish(), TrackListEvent::RESIZING, and UpdatePendingTracks().

Here is the call graph for this function:

PendingTracks() [2/2]

PendingTracks::PendingTracks ( const PendingTracks &  )

delete

~PendingTracks()

PendingTracks::~PendingTracks ( )

default

Member Function Documentation

ApplyPendingTracks()

bool PendingTracks::ApplyPendingTracks

(

)

Change the state of the project.

Strong guarantee for project state in case of exceptions. Will always clear the pending updates. Return true if the state of the track list really did change.

Exception safety guarantee:

Strong

Definition at line 227 of file PendingTracks.cpp.

{
   std::vector<std::shared_ptr<Track>> additions;
   auto updated = TrackList::Temporary(mTracks.GetOwner());
   {
      // Always clear, even if one of the update functions throws
      Finally Do{[&]{ ClearPendingTracks(&additions); }};
      UpdatePendingTracks();
      // Clear updaters before any more track list events are processed
      mUpdaters.clear();
      updated.swap(mPendingUpdates);
   }
 
   bool result = false;
 
   // Remaining steps must be No-fail-guarantee so that this function
   // gives Strong-guarantee
 
   std::vector<std::shared_ptr<Track>> reinstated;
 
   for (const auto pendingTrack : *updated)
      pendingTrack->ReparentAllAttachments();
 
   while (!updated->empty()) {
      auto iter = updated->begin();
      auto pendingTrack = *iter;
      auto src = mTracks.FindById(pendingTrack->GetId());
      if (src) {
         mTracks.ReplaceOne(*src, std::move(*updated));
         result = true;
      }
      else {
         // Perhaps a track marked for pending changes got deleted by
         // some other action.  Recreate it so we don't lose the
         // accumulated changes.
         reinstated.push_back(pendingTrack->SharedPointer());
         updated->Remove(*pendingTrack);
      }
   }
 
   // If there are tracks to reinstate, append them to the list.
   for (auto &pendingTrack : reinstated)
      if (pendingTrack)
         mTracks.Add(move(pendingTrack)), result = true;
 
   // Put the pending added tracks back into the list, preserving their
   // positions and assigning ids.
   auto iter = mTracks.begin();
   for (auto &pendingTrack : additions) {
      auto next = iter;
      ++next;
      if (pendingTrack)
         // This emits appropriate track list events
         mTracks.Insert(*iter, pendingTrack, true);
      else
         assert(iter != mTracks.end()); // Deduce that from ClearPendingTrack
      iter = next;
   }
 
   return result;
}

References TrackList::Add(), TrackList::begin(), ClearPendingTracks(), TrackList::end(), TrackList::FindById(), TrackList::GetOwner(), TrackList::Insert(), mPendingUpdates, mTracks, mUpdaters, TrackList::ReplaceOne(), TrackList::Temporary(), and UpdatePendingTracks().

Referenced by ProjectAudioManager::OnCommitRecording().

Here is the call graph for this function:

Here is the caller graph for this function:

ClearPendingTracks()

void PendingTracks::ClearPendingTracks

(

std::vector< std::shared_ptr< Track > > *

pAdded = nullptr

)

Forget pending track additions and changes;.

if requested, give back the pending added tracks, as channel groups, stored in the vector at their original positions in iteration order and nulls corresponding with non-added tracks in original iteration order; no trailing nulls

Exception safety guarantee:

No-fail

Definition at line 197 of file PendingTracks.cpp.

{
   mUpdaters.clear();
   mPendingUpdates->Clear();
 
   if (pAdded)
      pAdded->clear();
 
   auto [it, end] = mTracks.Any();
   while (it != end) {
      const auto pTrack = *it;
      ++it;
      if (pTrack->GetId() == TrackId{}) {
         if (pAdded)
            pAdded->emplace_back(mTracks.Remove(*pTrack));
      }
      else {
         if (pAdded)
            pAdded->push_back(nullptr);
      }
   }
 
   if (pAdded)
      // Remove trailing nulls
      while (!pAdded->empty() && !pAdded->back())
         pAdded->pop_back();
}

References TrackList::Any(), details::end(), mPendingUpdates, mTracks, mUpdaters, and TrackList::Remove().

Referenced by ApplyPendingTracks(), ProjectAudioManager::CancelRecording(), and AudacityApp::OnExceptionInMainLoop().

Here is the call graph for this function:

Here is the caller graph for this function:

DoSubstituteOriginalChannel()

std::pair< const Track *, const Channel * > PendingTracks::DoSubstituteOriginalChannel ( const Track &  track, size_t  channelIndex  ) const

private

Definition at line 116 of file PendingTracks.cpp.

{
   auto pTrack = &track;
   if (!mPendingUpdates->empty()) {
      const auto end = mPendingUpdates->end();
      // Find the shadow track with the id
      const auto pred = [id = track.GetId()](const auto &pTrack){
         return pTrack->GetId() == id; };
      if (const auto it =
          std::find_if(mPendingUpdates->begin(), end, pred); it != end)
      {
         const auto end2 = mTracks.end();
         // Find the original track with the id
         if (const auto it2 = std::find_if(mTracks.begin(), end2, pred)
            ; it2 != end2)
         {
            pTrack = *it2;
            // Find the correct corresponding channel
            const auto &channels = pTrack->Channels();
            const auto size = channels.size();
            // This should be provable from how RegisterPendingChangedTrack
            // constructs the substitutes
            assert(channelIndex < size);
 
            auto channelIter = channels.begin();
            std::advance(channelIter, std::min<int>(channelIndex, size - 1));
            return { pTrack, (*channelIter).get() };
         }
      }
   }
   return {};
}

References TrackList::begin(), TrackList::end(), details::end(), Track::GetId(), id, mPendingUpdates, mTracks, and size.

Referenced by SubstituteOriginalChannel(), and SubstituteOriginalTrack().

Here is the call graph for this function:

Here is the caller graph for this function:

DoSubstitutePendingChangedChannel()

std::pair< Track *, Channel * > PendingTracks::DoSubstitutePendingChangedChannel ( Track &  track, size_t  channelIndex  ) const

private

Definition at line 59 of file PendingTracks.cpp.

{
   // Linear search.  Tracks in a project are usually very few.
   auto pTrack = &track;
   if (!mPendingUpdates->empty()) {
      const auto end = mPendingUpdates->end();
      // Find the shadow track with the id
      const auto pred = [id = track.GetId()](const auto &pTrack){
         return pTrack->GetId() == id; };
      if (const auto it = std::find_if(mPendingUpdates->begin(), end, pred)
          ; it != end)
      {
         pTrack = *it;
         // Find the correct corresponding channel
         const auto &channels = pTrack->Channels();
         const auto size = channels.size();
         // This should be provable from how RegisterPendingChangedTrack
         // constructs the substitutes
         assert(channelIndex < size);
         auto channelIter = channels.begin();
         std::advance(channelIter, std::min<int>(channelIndex, size - 1));
         return { pTrack, (*channelIter).get() };
      }
   }
   return {};
}

References details::end(), Track::GetId(), id, mPendingUpdates, and size.

Referenced by SubstitutePendingChangedChannel(), and SubstitutePendingChangedTrack().

Here is the call graph for this function:

Here is the caller graph for this function:

Get() [1/2]

PendingTracks & PendingTracks::Get ( AudacityProject &  project )

static

Definition at line 21 of file PendingTracks.cpp.

{
   return project.AttachedObjects::Get<PendingTracks>(sPendingTracksKey);
}

References project, and sPendingTracksKey.

Referenced by ProjectAudioManager::CancelRecording(), anonymous_namespace{UndoTracks.cpp}::TrackListRestorer::CanUndoOrRedo(), CloseButtonHandle::CommitChanges(), ProjectAudioManager::DoRecord(), TrackPanel::DrawTracks(), Get(), CommonChannelView::GetMinimizedHeight(), NoteTrackAffordanceControls::HitTest(), WaveTrackAffordanceControls::HitTest(), SyncLock::IsSyncLockSelected(), MixerBoard::MixerBoard(), ProjectAudioManager::OnCommitRecording(), AudacityApp::OnExceptionInMainLoop(), TrackPanel::ProcessUIHandleResult(), RealtimeEffectPanel::RealtimeEffectPanel(), TrackPanel::TrackPanel(), anonymous_namespace{ChannelView.cpp}::TrackPositioner::TrackPositioner(), Viewport::UpdateScrollbarsForTracks(), and ProjectFileIO::WriteXML().

Here is the caller graph for this function:

Get() [2/2]

const PendingTracks & PendingTracks::Get ( const AudacityProject &  project )

static

Definition at line 26 of file PendingTracks.cpp.

{
   return Get(const_cast<AudacityProject &>(project));
}

References Get(), and project.

Here is the call graph for this function:

HasPendingTracks()

bool PendingTracks::HasPendingTracks

(

)

const

Definition at line 289 of file PendingTracks.cpp.

{
   if (!mPendingUpdates->empty())
      return true;
   const auto end = mTracks.end();
   return (end != std::find_if(mTracks.begin(), end, [](const Track *t){
      return t->GetId() == TrackId{};
   }));
}

References TrackList::begin(), TrackList::end(), details::end(), mPendingUpdates, and mTracks.

Referenced by anonymous_namespace{UndoTracks.cpp}::TrackListRestorer::CanUndoOrRedo().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=()

PendingTracks & PendingTracks::operator= ( const PendingTracks &  )

delete

RegisterPendingChangedTrack()

Track * PendingTracks::RegisterPendingChangedTrack	(	Updater	updater,
		Track *	src
	)

Start a deferred update of the project.

The return value is a duplicate of the given track. While ApplyPendingTracks or ClearPendingTracks is not yet called, there may be other direct changes to the project that push undo history. Meanwhile the returned object can accumulate other changes for a deferred push, and temporarily shadow the actual project track for display purposes. The Updater function, if not null, merges state (from the actual project into the pending track) which is not meant to be overridden by the accumulated pending changes. Pending track will have the same TrackId as the actual. Pending changed tracks will not occur in iterations.

Definition at line 168 of file PendingTracks.cpp.

{
   auto track =
      src->Duplicate(Track::DuplicateOptions{}.ShallowCopyAttachments());
 
   mUpdaters.push_back(move(updater));
   mPendingUpdates->Add(track);
   return track.get();
}

References Track::Duplicate(), mPendingUpdates, mUpdaters, Track::DuplicateOptions::ShallowCopyAttachments(), and updater.

Here is the call graph for this function:

RegisterPendingNewTracks()

void PendingTracks::RegisterPendingNewTracks

(

TrackList &&

list

)

Like RegisterPendingChangedTrack, but for a list of new tracks, not a replacement track.

Caller supplies the list, and there are no updates. Pending tracks will have an unassigned TrackId. Pending new tracks WILL occur in iterations, always after actual tracks, and in the sequence that they were added. They can be distinguished from actual tracks because they have default TrackId.

Definition at line 53 of file PendingTracks.cpp.

{
   mTracks.Append(std::move(list), false);
}

References TrackList::Append(), and mTracks.

Here is the call graph for this function:

SubstituteOriginalChannel()

const Channel & PendingTracks::SubstituteOriginalChannel

(

const Channel &

channel

)

const

If the channel is in a pending changed track, return the corresponding original; else return the channel

Definition at line 150 of file PendingTracks.cpp.

{
   const auto pTrack =
      dynamic_cast<const Track *>(&channel.GetChannelGroup());
   if (!pTrack)
      return channel;
   const auto index = channel.GetChannelIndex();
   const auto [_, pChannel] = DoSubstituteOriginalChannel(*pTrack, index);
   return pChannel ? *pChannel : channel;
}

References _, DoSubstituteOriginalChannel(), Channel::GetChannelGroup(), and Channel::GetChannelIndex().

Referenced by CommonChannelView::GetMinimizedHeight().

Here is the call graph for this function:

Here is the caller graph for this function:

SubstituteOriginalTrack()

const Track & PendingTracks::SubstituteOriginalTrack

(

const Track &

track

)

const

If the track is a pending changed track, return the corresponding original; else return the track

Definition at line 162 of file PendingTracks.cpp.

{
   const auto [pTrack, _] = DoSubstituteOriginalChannel(track, 0);
   return pTrack ? *pTrack : track;
}

References _, and DoSubstituteOriginalChannel().

Referenced by SyncLock::IsSyncLockSelected().

Here is the call graph for this function:

Here is the caller graph for this function:

SubstitutePendingChangedChannel() [1/2]

Channel & PendingTracks::SubstitutePendingChangedChannel

(

Channel &

channel

)

const

Find anything registered with TrackList::RegisterPendingChangedTrack and not yet cleared or applied; if no such exists, return the given channel

Definition at line 87 of file PendingTracks.cpp.

{
   const auto pTrack = dynamic_cast<Track *>(&channel.GetChannelGroup());
   if (!pTrack)
      return channel;
   const auto index = channel.GetChannelIndex();
   auto [_, pChannel] = DoSubstitutePendingChangedChannel(*pTrack, index);
   return pChannel ? *pChannel : channel;
}

References _, DoSubstitutePendingChangedChannel(), Channel::GetChannelGroup(), and Channel::GetChannelIndex().

Referenced by SubstitutePendingChangedChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

SubstitutePendingChangedChannel() [2/2]

const Channel & PendingTracks::SubstitutePendingChangedChannel

(

const Channel &

channel

)

const

Definition at line 98 of file PendingTracks.cpp.

{
   return SubstitutePendingChangedChannel(const_cast<Channel&>(channel));
}

References SubstitutePendingChangedChannel().

Here is the call graph for this function:

SubstitutePendingChangedTrack() [1/2]

const Track & PendingTracks::SubstitutePendingChangedTrack

(

const Track &

track

)

const

Definition at line 109 of file PendingTracks.cpp.

{
   return SubstitutePendingChangedTrack(const_cast<Track&>(track));
}

References SubstitutePendingChangedTrack().

Here is the call graph for this function:

SubstitutePendingChangedTrack() [2/2]

Track & PendingTracks::SubstitutePendingChangedTrack

(

Track &

track

)

const

Find anything registered with TrackList::RegisterPendingChangedTrack and not yet cleared or applied; if no such exists, return the given track

Definition at line 103 of file PendingTracks.cpp.

{
   auto [pTrack, _] = DoSubstitutePendingChangedChannel(track, 0);
   return pTrack ? *pTrack : track;
}

References _, and DoSubstitutePendingChangedChannel().

Referenced by CloseButtonHandle::CommitChanges(), NoteTrackAffordanceControls::HitTest(), WaveTrackAffordanceControls::HitTest(), and SubstitutePendingChangedTrack().

Here is the call graph for this function:

Here is the caller graph for this function:

UpdatePendingTracks()

void PendingTracks::UpdatePendingTracks

(

)

Invoke the updaters of pending tracks. Pass any exceptions from the updater functions.

Definition at line 178 of file PendingTracks.cpp.

{
   if (mPendingUpdates->empty())
      return;
   auto pUpdater = mUpdaters.begin();
   for (const auto &pendingTrack : *mPendingUpdates) {
      auto src = mTracks.FindById(pendingTrack->GetId());
      // Copy just a part of the track state, according to the update
      // function
      const auto &updater = *pUpdater;
      if (pendingTrack && src) {
         if (updater)
            updater(*pendingTrack, *src);
      }
      ++pUpdater;
   }
}

References TrackList::FindById(), mPendingUpdates, mTracks, mUpdaters, anonymous_namespace{LogWindow.cpp}::pUpdater, and updater.

Referenced by ApplyPendingTracks(), PendingTracks(), and TrackPanel::ProcessUIHandleResult().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mPendingUpdates

std::shared_ptr<TrackList> PendingTracks::mPendingUpdates

private

Definition at line 123 of file PendingTracks.h.

Referenced by ApplyPendingTracks(), ClearPendingTracks(), DoSubstituteOriginalChannel(), DoSubstitutePendingChangedChannel(), HasPendingTracks(), RegisterPendingChangedTrack(), and UpdatePendingTracks().

mTrackListSubscription

Observer::Subscription PendingTracks::mTrackListSubscription

private

Definition at line 121 of file PendingTracks.h.

mTracks

TrackList& PendingTracks::mTracks

private

Definition at line 120 of file PendingTracks.h.

Referenced by ApplyPendingTracks(), ClearPendingTracks(), DoSubstituteOriginalChannel(), HasPendingTracks(), RegisterPendingNewTracks(), and UpdatePendingTracks().

mUpdaters

std::vector<Updater> PendingTracks::mUpdaters

private

Definition at line 122 of file PendingTracks.h.

Referenced by ApplyPendingTracks(), ClearPendingTracks(), RegisterPendingChangedTrack(), and UpdatePendingTracks().

---

The documentation for this class was generated from the following files:

• PendingTracks.h
• PendingTracks.cpp