KiCad PCB EDA Suite
FOOTPRINT_ASYNC_LOADER Class Reference

This class can be used to populate a FOOTPRINT_LIST asynchronously. More...

#include <footprint_info.h>

Public Member Functions

 FOOTPRINT_ASYNC_LOADER ()
 Construct an asynchronous loader. More...
 
void SetList (FOOTPRINT_LIST *aList)
 Assign a FOOTPRINT_LIST to the loader. More...
 
void Start (FP_LIB_TABLE *aTable, wxString const *aNickname=nullptr, unsigned aNThreads=DEFAULT_THREADS)
 Launch the worker threads. More...
 
bool Join ()
 Wait until the worker threads are finished, and then perform any required single-threaded finishing on the list. More...
 
int GetProgress () const
 Get the current completion percentage. More...
 
void SetCompletionCallback (std::function< void()> aCallback)
 Set a callback to receive notice when loading is complete. More...
 
bool IsSameTable (FP_LIB_TABLE *aOther)
 Return true if the given table is the same as the last table loaded. More...
 

Static Public Attributes

static constexpr unsigned DEFAULT_THREADS = 6
 Default number of worker threads. More...
 

Private Attributes

FOOTPRINT_LISTm_list
 
std::function< void()> m_completion_cb
 
std::string m_last_table
 
bool m_started
 True if Start() has been called - does not reset. More...
 
int m_total_libs
 

Friends

class FOOTPRINT_LIST
 
class FOOTPRINT_LIST_IMPL
 

Detailed Description

This class can be used to populate a FOOTPRINT_LIST asynchronously.

Constructing one, calling .Start(), then waiting until it reports completion is equivalent to calling FOOTPRINT_LIST::ReadFootprintFiles().

Definition at line 297 of file footprint_info.h.

Constructor & Destructor Documentation

FOOTPRINT_ASYNC_LOADER::FOOTPRINT_ASYNC_LOADER ( )

Construct an asynchronous loader.

Definition at line 142 of file footprint_info.cpp.

References m_started, and m_total_libs.

142  : m_list( nullptr )
143 {
144  m_started = false;
145  m_total_libs = 0;
146 }
FOOTPRINT_LIST * m_list
bool m_started
True if Start() has been called - does not reset.

Member Function Documentation

int FOOTPRINT_ASYNC_LOADER::GetProgress ( ) const

Get the current completion percentage.

0 and 100 are reserved values: 0 will only be returned if Start() has not yet been called, and 100 will only be returned if totally complete (i.e. rounding errors will never cause a 100% progress despite not being complete).

If there are no libraries at all, returns 100 (as loading zero libraries is always complete).

Threadsafe.

Definition at line 183 of file footprint_info.cpp.

References FOOTPRINT_LIST::CountFinished(), m_list, m_started, and m_total_libs.

Referenced by FOOTPRINT_SELECT_WIDGET::Load(), and FOOTPRINT_SELECT_WIDGET::OnProgressTimer().

184 {
185  if( !m_started )
186  return 0;
187  else if( m_total_libs == 0 || !m_list )
188  return 100;
189  else
190  {
191  int loaded = m_list->CountFinished();
192  int prog = ( 100 * loaded ) / m_total_libs;
193 
194  if( loaded == m_total_libs )
195  return 100;
196  else if( loaded < m_total_libs && prog >= 100 )
197  return 99;
198  else if( prog <= 0 )
199  return 1;
200  else
201  return prog;
202  }
203 }
FOOTPRINT_LIST * m_list
bool m_started
True if Start() has been called - does not reset.
virtual size_t CountFinished()=0
Return the number of libraries finished (successfully or otherwise).
bool FOOTPRINT_ASYNC_LOADER::IsSameTable ( FP_LIB_TABLE aOther)

Return true if the given table is the same as the last table loaded.

Useful for checking if the table has been modified and needs to be reloaded.

Definition at line 212 of file footprint_info.cpp.

References FP_LIB_TABLE::Format(), STRING_FORMATTER::GetString(), and m_last_table.

Referenced by FOOTPRINT_SELECT_WIDGET::Load().

213 {
214  STRING_FORMATTER sof;
215  aOther->Format( &sof, 0 );
216  return m_last_table == sof.GetString();
217 }
const std::string & GetString()
Definition: richio.h:475
virtual void Format(OUTPUTFORMATTER *aOutput, int aIndentLevel) const override
Generate the table in s-expression format to aOutput with an indention level of aIndentLevel.
Class STRING_FORMATTER implements OUTPUTFORMATTER to a memory buffer.
Definition: richio.h:445
bool FOOTPRINT_ASYNC_LOADER::Join ( )

Wait until the worker threads are finished, and then perform any required single-threaded finishing on the list.

This must be called before using the list, even if the completion callback was used!

It is safe to call this method from a thread, but it is not safe to use the list from ANY thread until it completes. It is recommended to call this from the main thread because of this.

It is safe to call this multiple times, but after the first it will always return true.

Returns
true if no errors occurred

Definition at line 170 of file footprint_info.cpp.

References FOOTPRINT_LIST::JoinWorkers(), and m_list.

Referenced by FOOTPRINT_SELECT_WIDGET::OnProgressTimer(), and FOOTPRINT_LIST_IMPL::ReadFootprintFiles().

171 {
172  if( m_list )
173  {
174  bool rv = m_list->JoinWorkers();
175  m_list = nullptr;
176  return rv;
177  }
178  else
179  return true;
180 }
virtual bool JoinWorkers()=0
Join worker threads.
FOOTPRINT_LIST * m_list
void FOOTPRINT_ASYNC_LOADER::SetCompletionCallback ( std::function< void()>  aCallback)

Set a callback to receive notice when loading is complete.

Callback MUST be threadsafe, and must be set before calling Start if you want to use it (it is safe not to set it at all).

Definition at line 206 of file footprint_info.cpp.

References m_completion_cb.

207 {
208  m_completion_cb = aCallback;
209 }
std::function< void()> m_completion_cb
void FOOTPRINT_ASYNC_LOADER::SetList ( FOOTPRINT_LIST aList)

Assign a FOOTPRINT_LIST to the loader.

This does not take ownership of the list.

Definition at line 149 of file footprint_info.cpp.

References m_list.

Referenced by FOOTPRINT_SELECT_WIDGET::Load(), and FOOTPRINT_LIST_IMPL::ReadFootprintFiles().

150 {
151  m_list = aList;
152 }
FOOTPRINT_LIST * m_list
void FOOTPRINT_ASYNC_LOADER::Start ( FP_LIB_TABLE aTable,
wxString const *  aNickname = nullptr,
unsigned  aNThreads = DEFAULT_THREADS 
)

Launch the worker threads.

Parameters
aTabledefines all the libraries.
aNicknameis the library to read from, or if NULL means read all footprints from all known libraries in aTable.
aNThreadsis the number of worker threads.

Definition at line 155 of file footprint_info.cpp.

References FP_LIB_TABLE::Format(), STRING_FORMATTER::GetString(), m_last_table, m_list, m_started, and FOOTPRINT_LIST::StartWorkers().

Referenced by FOOTPRINT_SELECT_WIDGET::Load(), and FOOTPRINT_LIST_IMPL::ReadFootprintFiles().

157 {
158  m_started = true;
159 
160  // Capture the FP_LIB_TABLE into m_last_table. Formatting it as a string instead of storing the
161  // raw data avoids having to pull in the FP-specific parts.
162  STRING_FORMATTER sof;
163  aTable->Format( &sof, 0 );
164  m_last_table = sof.GetString();
165 
166  m_list->StartWorkers( aTable, aNickname, this, aNThreads );
167 }
FOOTPRINT_LIST * m_list
bool m_started
True if Start() has been called - does not reset.
const std::string & GetString()
Definition: richio.h:475
virtual void Format(OUTPUTFORMATTER *aOutput, int aIndentLevel) const override
Generate the table in s-expression format to aOutput with an indention level of aIndentLevel.
Class STRING_FORMATTER implements OUTPUTFORMATTER to a memory buffer.
Definition: richio.h:445
virtual void StartWorkers(FP_LIB_TABLE *aTable, wxString const *aNickname, FOOTPRINT_ASYNC_LOADER *aLoader, unsigned aNThreads)=0
Launch worker threads to load footprints.

Friends And Related Function Documentation

friend class FOOTPRINT_LIST
friend

Definition at line 299 of file footprint_info.h.

friend class FOOTPRINT_LIST_IMPL
friend

Definition at line 300 of file footprint_info.h.

Member Data Documentation

constexpr unsigned FOOTPRINT_ASYNC_LOADER::DEFAULT_THREADS = 6
static

Default number of worker threads.

Determined empirically (by dickelbeck): More than 6 is not significantly faster, less than 6 is likely slower.

Definition at line 379 of file footprint_info.h.

std::function<void()> FOOTPRINT_ASYNC_LOADER::m_completion_cb
private

Definition at line 303 of file footprint_info.h.

Referenced by FOOTPRINT_LIST_IMPL::loader_job(), and SetCompletionCallback().

std::string FOOTPRINT_ASYNC_LOADER::m_last_table
private

Definition at line 304 of file footprint_info.h.

Referenced by IsSameTable(), and Start().

FOOTPRINT_LIST* FOOTPRINT_ASYNC_LOADER::m_list
private

Definition at line 302 of file footprint_info.h.

Referenced by FOOTPRINT_LIST::GetList(), GetProgress(), Join(), SetList(), and Start().

bool FOOTPRINT_ASYNC_LOADER::m_started
private

True if Start() has been called - does not reset.

Definition at line 306 of file footprint_info.h.

Referenced by FOOTPRINT_ASYNC_LOADER(), GetProgress(), and Start().

int FOOTPRINT_ASYNC_LOADER::m_total_libs
private

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