LLDB mainline
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
lldb_private::ThreadedCommunication Class Reference

"lldb/Core/ThreadedCommunication.h" Variation of Communication that supports threaded reads. More...

#include <ThreadedCommunication.h>

Inheritance diagram for lldb_private::ThreadedCommunication:
Inheritance graph
[legend]

Public Types

typedef void(* ReadThreadBytesReceived) (void *baton, const void *src, size_t src_len)
 

Public Member Functions

 FLAGS_ANONYMOUS_ENUM ()
 
 ThreadedCommunication (const char *broadcaster_name)
 Construct the ThreadedCommunication object with the specified name for the Broadcaster that this object inherits from.
 
 ~ThreadedCommunication () override
 Destructor.
 
void Clear () override
 
lldb::ConnectionStatus Disconnect (Status *error_ptr=nullptr) override
 Disconnect the communications connection if one is currently connected.
 
size_t Read (void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr) override
 Read bytes from the current connection.
 
void SetConnection (std::unique_ptr< Connection > connection) override
 Sets the connection that it to be used by this class.
 
virtual bool StartReadThread (Status *error_ptr=nullptr)
 Starts a read thread whose sole purpose it to read bytes from the current connection.
 
virtual bool StopReadThread (Status *error_ptr=nullptr)
 Stops the read thread by cancelling it.
 
virtual bool JoinReadThread (Status *error_ptr=nullptr)
 
bool ReadThreadIsRunning ()
 Checks if there is a currently running read thread.
 
lldb::thread_result_t ReadThread ()
 The read thread function.
 
void SetReadThreadBytesReceivedCallback (ReadThreadBytesReceived callback, void *callback_baton)
 
void SynchronizeWithReadThread ()
 Wait for the read thread to process all outstanding data.
 
ConstStringGetBroadcasterClass () const override
 This needs to be filled in if you are going to register the broadcaster with the broadcaster manager and do broadcaster class matching.
 
- Public Member Functions inherited from lldb_private::Communication
 Communication ()
 Construct the Communication object.
 
virtual ~Communication ()
 Destructor.
 
virtual void Clear ()
 
lldb::ConnectionStatus Connect (const char *url, Status *error_ptr)
 Connect using the current connection by passing url to its connect function.
 
virtual lldb::ConnectionStatus Disconnect (Status *error_ptr=nullptr)
 Disconnect the communications connection if one is currently connected.
 
bool IsConnected () const
 Check if the connection is valid.
 
bool HasConnection () const
 
lldb_private::ConnectionGetConnection ()
 
virtual size_t Read (void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)
 Read bytes from the current connection.
 
size_t Write (const void *src, size_t src_len, lldb::ConnectionStatus &status, Status *error_ptr)
 The actual write function that attempts to write to the communications protocol.
 
size_t WriteAll (const void *src, size_t src_len, lldb::ConnectionStatus &status, Status *error_ptr)
 Repeatedly attempt writing until either src_len bytes are written or a permanent failure occurs.
 
virtual void SetConnection (std::unique_ptr< Connection > connection)
 Sets the connection that it to be used by this class.
 
bool GetCloseOnEOF () const
 
void SetCloseOnEOF (bool b)
 
- Public Member Functions inherited from lldb_private::Broadcaster
 Broadcaster (lldb::BroadcasterManagerSP manager_sp, std::string name)
 Construct with a broadcaster with a name.
 
virtual ~Broadcaster ()
 Destructor.
 
void CheckInWithManager ()
 
void BroadcastEvent (lldb::EventSP &event_sp)
 Broadcast an event which has no associated data.
 
void BroadcastEventIfUnique (lldb::EventSP &event_sp)
 
void BroadcastEvent (uint32_t event_type, const lldb::EventDataSP &event_data_sp)
 
void BroadcastEvent (uint32_t event_type)
 
void BroadcastEventIfUnique (uint32_t event_type)
 
void Clear ()
 
virtual void AddInitialEventsToListener (const lldb::ListenerSP &listener_sp, uint32_t requested_events)
 
uint32_t AddListener (const lldb::ListenerSP &listener_sp, uint32_t event_mask)
 Listen for any events specified by event_mask.
 
const std::string & GetBroadcasterName ()
 Get this broadcaster's name.
 
bool GetEventNames (Stream &s, const uint32_t event_mask, bool prefix_with_broadcaster_name) const
 Get the event name(s) for one or more event bits.
 
void SetEventName (uint32_t event_mask, const char *name)
 Set the name for an event bit.
 
const char * GetEventName (uint32_t event_mask) const
 
bool EventTypeHasListeners (uint32_t event_type)
 
bool RemoveListener (const lldb::ListenerSP &listener_sp, uint32_t event_mask=UINT32_MAX)
 Removes a Listener from this broadcasters list and frees the event bits specified by event_mask that were previously acquired by listener (assuming listener was listening to this object) for other listener objects to use.
 
bool HijackBroadcaster (const lldb::ListenerSP &listener_sp, uint32_t event_mask=UINT32_MAX)
 Provides a simple mechanism to temporarily redirect events from broadcaster.
 
bool IsHijackedForEvent (uint32_t event_mask)
 
void RestoreBroadcaster ()
 Restore the state of the Broadcaster from a previous hijack attempt.
 
virtual ConstStringGetBroadcasterClass () const
 This needs to be filled in if you are going to register the broadcaster with the broadcaster manager and do broadcaster class matching.
 
lldb::BroadcasterManagerSP GetManager ()
 
void SetPrimaryListener (lldb::ListenerSP listener_sp)
 
lldb::ListenerSP GetPrimaryListener ()
 

Static Public Member Functions

static ConstStringGetStaticBroadcasterClass ()
 
- Static Public Member Functions inherited from lldb_private::Communication
static std::string ConnectionStatusAsString (lldb::ConnectionStatus status)
 

Protected Member Functions

virtual void AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast, lldb::ConnectionStatus status)
 Append new bytes that get read from the read thread into the internal object byte cache.
 
size_t GetCachedBytes (void *dst, size_t dst_len)
 Get any available bytes from our data cache.
 
- Protected Member Functions inherited from lldb_private::Communication
size_t ReadFromConnection (void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)
 
- Protected Member Functions inherited from lldb_private::Broadcaster
BroadcasterImplSP GetBroadcasterImpl ()
 
const char * GetHijackingListenerName ()
 

Protected Attributes

std::atomic< bool > m_read_thread_enabled
 Whether the read thread is enabled.
 
std::atomic< bool > m_read_thread_did_exit
 Whether the read thread is enabled.
 
std::string m_bytes
 A buffer to cache bytes read in the ReadThread function.
 
std::recursive_mutex m_bytes_mutex
 A mutex to protect multi-threaded access to the cached bytes.
 
lldb::ConnectionStatus m_pass_status
 Connection status passthrough from read thread.
 
Status m_pass_error
 Error passthrough from read thread.
 
std::mutex m_synchronize_mutex
 
ReadThreadBytesReceived m_callback
 
void * m_callback_baton
 
HostThread m_read_thread
 The read thread handle in case we need to cancel the thread.
 
std::mutex m_read_thread_mutex
 
- Protected Attributes inherited from lldb_private::Communication
lldb::ConnectionSP m_connection_sp
 The connection that is current in use by this communications class.
 
std::mutex m_write_mutex
 Don't let multiple threads write at the same time...
 
bool m_close_on_eof
 

Private Member Functions

 ThreadedCommunication (const ThreadedCommunication &)=delete
 
const ThreadedCommunicationoperator= (const ThreadedCommunication &)=delete
 
 Communication ()
 Construct the Communication object.
 

Additional Inherited Members

- Protected Types inherited from lldb_private::Broadcaster
typedef std::shared_ptr< BroadcasterImplBroadcasterImplSP
 
typedef std::weak_ptr< BroadcasterImplBroadcasterImplWP
 

Detailed Description

"lldb/Core/ThreadedCommunication.h" Variation of Communication that supports threaded reads.

ThreadedCommunication enhances the base Communication class with support for multi-threaded mode. In this mode, a read thread is spawned that continually reads data and caches any received bytes. To start the read thread clients call:

bool ThreadedCommunication::StartReadThread (Status *);

If true is returned a read thread has been spawned that will continually execute a call to the pure virtual DoRead function:

size_t Communication::ReadFromConnection (void *, size_t, uint32_t);

When bytes are received the data gets cached in m_bytes and this class will broadcast a eBroadcastBitReadThreadGotBytes event. Clients that want packet based communication should override AppendBytesToCache. The subclasses can choose to call the built in AppendBytesToCache with the broadcast parameter set to false. This will cause the eBroadcastBitReadThreadGotBytes event not get broadcast, and then the subclass can post a eBroadcastBitPacketAvailable event when a full packet of data has been received.

If the connection is disconnected a eBroadcastBitDisconnected event gets broadcast. If the read thread exits a eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also post a eBroadcastBitReadThreadShouldExit event to this object which will cause the read thread to exit.

ThreadedCommunication inherits from Broadcaster which means it can be used in conjunction with Listener to wait for multiple broadcaster objects and multiple events from each of those objects. ThreadedCommunication defines a set of pre-defined event bits (see enumerations definitions that start with "eBroadcastBit" below).

Definition at line 61 of file ThreadedCommunication.h.

Member Typedef Documentation

◆ ReadThreadBytesReceived

typedef void(* lldb_private::ThreadedCommunication::ReadThreadBytesReceived) (void *baton, const void *src, size_t src_len)

Definition at line 82 of file ThreadedCommunication.h.

Constructor & Destructor Documentation

◆ ThreadedCommunication() [1/2]

ThreadedCommunication::ThreadedCommunication ( const char *  broadcaster_name)

Construct the ThreadedCommunication object with the specified name for the Broadcaster that this object inherits from.

Parameters
[in]broadcaster_nameThe name of the broadcaster object. This name should be as complete as possible to uniquely identify this object. The broadcaster name can be updated after the connect function is called.

Definition at line 40 of file ThreadedCommunication.cpp.

References lldb_private::Broadcaster::CheckInWithManager(), lldb_private::Communication, lldb_private::GetLog(), LLDB_LOG, lldb_private::Object, and lldb_private::Broadcaster::SetEventName().

◆ ~ThreadedCommunication()

ThreadedCommunication::~ThreadedCommunication ( )
override

Destructor.

The destructor is virtual since this class gets subclassed.

Definition at line 58 of file ThreadedCommunication.cpp.

References lldb_private::Communication, lldb_private::Broadcaster::GetBroadcasterName(), lldb_private::GetLog(), LLDB_LOG, and lldb_private::Object.

◆ ThreadedCommunication() [2/2]

lldb_private::ThreadedCommunication::ThreadedCommunication ( const ThreadedCommunication )
privatedelete

Member Function Documentation

◆ AppendBytesToCache()

void ThreadedCommunication::AppendBytesToCache ( const uint8_t *  src,
size_t  src_len,
bool  broadcast,
lldb::ConnectionStatus  status 
)
protectedvirtual

Append new bytes that get read from the read thread into the internal object byte cache.

This will cause a eBroadcastBitReadThreadGotBytes event to be broadcast if broadcast is true.

Subclasses can override this function in order to inspect the received data and check if a packet is available.

Subclasses can also still call this function from the overridden method to allow the caching to correctly happen and suppress the broadcasting of the eBroadcastBitReadThreadGotBytes event by setting broadcast to false.

Parameters
[in]srcA source buffer that must be at least src_len bytes long.
[in]src_lenThe number of bytes to append to the cache.

Definition at line 239 of file ThreadedCommunication.cpp.

References lldb_private::Broadcaster::BroadcastEventIfUnique(), lldb_private::Communication, lldb::eConnectionStatusEndOfFile, lldb_private::GetLog(), LLDB_LOG, m_bytes, m_bytes_mutex, m_callback, and m_callback_baton.

Referenced by ReadThread().

◆ Clear()

void ThreadedCommunication::Clear ( )
overridevirtual

◆ Communication()

Communication::Communication ( )
private

Construct the Communication object.

Definition at line 42 of file Communication.cpp.

◆ Disconnect()

ConnectionStatus ThreadedCommunication::Disconnect ( Status error_ptr = nullptr)
overridevirtual

Disconnect the communications connection if one is currently connected.

Returns
True if the disconnect succeeded, false otherwise. The internal error object should be filled in with an appropriate value based on the result of this function.
See also
Status& Communication::GetError ();
bool Connection::Disconnect ();

Reimplemented from lldb_private::Communication.

Definition at line 70 of file ThreadedCommunication.cpp.

References lldb_private::Communication::Disconnect(), m_read_thread_did_exit, and m_read_thread_enabled.

Referenced by lldb::SBCommunication::AdoptFileDesriptor(), lldb_private::Process::DestroyImpl(), lldb::SBCommunication::Disconnect(), Read(), ReadThread(), lldb_private::Process::ShouldBroadcastEvent(), and lldb_private::ScriptInterpreterIORedirect::~ScriptInterpreterIORedirect().

◆ FLAGS_ANONYMOUS_ENUM()

lldb_private::ThreadedCommunication::FLAGS_ANONYMOUS_ENUM ( )
inline

< Sent when the communications connection is lost.

< Sent by the read thread when bytes become available.

< Sent by the read thread when it exits to inform clients.

< Sent by clients that need to cancel the read thread.

< Sent when data received makes a complete packet.

< Sent by the read thread to indicate all pending input has been processed.

Definition at line 65 of file ThreadedCommunication.h.

◆ GetBroadcasterClass()

ConstString & lldb_private::ThreadedCommunication::GetBroadcasterClass ( ) const
inlineoverridevirtual

This needs to be filled in if you are going to register the broadcaster with the broadcaster manager and do broadcaster class matching.

FIXME: Probably should make a ManagedBroadcaster subclass with all the bits needed to work with the BroadcasterManager, so that it is clearer how to add one.

Reimplemented from lldb_private::Broadcaster.

Definition at line 221 of file ThreadedCommunication.h.

References GetStaticBroadcasterClass().

◆ GetCachedBytes()

size_t ThreadedCommunication::GetCachedBytes ( void *  dst,
size_t  dst_len 
)
protected

Get any available bytes from our data cache.

If this call empties the data cache, the eBroadcastBitReadThreadGotBytes event will be reset to signify no more bytes are available.

Parameters
[in]dstA destination buffer that must be at least dst_len bytes long.
[in]dst_lenThe number of bytes to attempt to read from the cache, and also the max number of bytes that can be placed into dst.
Returns
The number of bytes extracted from the data cache.

Definition at line 221 of file ThreadedCommunication.cpp.

References m_bytes, and m_bytes_mutex.

Referenced by Read().

◆ GetStaticBroadcasterClass()

ConstString & ThreadedCommunication::GetStaticBroadcasterClass ( )
static

◆ JoinReadThread()

bool ThreadedCommunication::JoinReadThread ( Status error_ptr = nullptr)
virtual

◆ operator=()

const ThreadedCommunication & lldb_private::ThreadedCommunication::operator= ( const ThreadedCommunication )
privatedelete

◆ Read()

size_t ThreadedCommunication::Read ( void *  dst,
size_t  dst_len,
const Timeout< std::micro > &  timeout,
lldb::ConnectionStatus status,
Status error_ptr 
)
overridevirtual

Read bytes from the current connection.

If no read thread is running, this function call the connection's Connection::Read(...) function to get any available.

If a read thread has been started, this function will check for any cached bytes that have already been read and return any currently available bytes. If no bytes are cached, it will wait for the bytes to become available by listening for the eBroadcastBitReadThreadGotBytes event. If this function consumes all of the bytes in the cache, it will reset the eBroadcastBitReadThreadGotBytes event bit.

Parameters
[in]dstA destination buffer that must be at least dst_len bytes long.
[in]dst_lenThe number of bytes to attempt to read, and also the max number of bytes that can be placed into dst.
[in]timeoutA timeout value or std::nullopt for no timeout.
Returns
The number of bytes actually read.
See also
size_t Connection::Read (void *, size_t);

Reimplemented from lldb_private::Communication.

Definition at line 76 of file ThreadedCommunication.cpp.

References lldb_private::Communication, Disconnect(), lldb::eConnectionStatusNoConnection, lldb::eConnectionStatusSuccess, lldb::eConnectionStatusTimedOut, GetCachedBytes(), lldb_private::Communication::GetCloseOnEOF(), lldb_private::GetLog(), LLDB_LOG, lldb_private::Communication::m_connection_sp, m_pass_error, m_pass_status, m_read_thread_did_exit, m_read_thread_enabled, lldb_private::Listener::MakeListener(), lldb_private::Communication::Read(), and lldb_private::Status::SetErrorString().

Referenced by lldb::SBCommunication::Read().

◆ ReadThread()

lldb::thread_result_t ThreadedCommunication::ReadThread ( )

The read thread function.

This function will call the "DoRead" function continuously and wait for data to become available. When data is received it will append the available data to the internal cache and broadcast a eBroadcastBitReadThreadGotBytes event.

Parameters
[in]comm_ptrA pointer to an instance of this class.
Returns
NULL.
See also
void Communication::ReadThreadGotBytes (const uint8_t *, size_t);

Definition at line 265 of file ThreadedCommunication.cpp.

References AppendBytesToCache(), lldb_private::Broadcaster::BroadcastEvent(), lldb_private::Communication, lldb_private::Communication::ConnectionStatusAsString(), Disconnect(), lldb::eConnectionStatusEndOfFile, lldb::eConnectionStatusError, lldb::eConnectionStatusInterrupted, lldb::eConnectionStatusLostConnection, lldb::eConnectionStatusNoConnection, lldb::eConnectionStatusSuccess, lldb::eConnectionStatusTimedOut, lldb::eErrorTypePOSIX, error(), lldb_private::Communication::GetCloseOnEOF(), lldb_private::GetLog(), LLDB_LOG, m_pass_error, m_pass_status, m_read_thread_did_exit, m_read_thread_enabled, m_synchronize_mutex, and lldb_private::Communication::ReadFromConnection().

Referenced by StartReadThread().

◆ ReadThreadIsRunning()

bool ThreadedCommunication::ReadThreadIsRunning ( )

Checks if there is a currently running read thread.

Returns
True if the read thread is running, false otherwise.

Definition at line 261 of file ThreadedCommunication.cpp.

References m_read_thread_enabled.

Referenced by lldb::SBCommunication::ReadThreadIsRunning().

◆ SetConnection()

void ThreadedCommunication::SetConnection ( std::unique_ptr< Connection connection)
overridevirtual

Sets the connection that it to be used by this class.

By making a communication class that uses different connections it allows a single communication interface to negotiate and change its connection without any interruption to the client. It also allows the Communication class to be subclassed for packet based communication.

Parameters
[in]connectionA connection that this class will own and destroy.
See also
class Connection

Reimplemented from lldb_private::Communication.

Definition at line 372 of file ThreadedCommunication.cpp.

References lldb_private::Communication::SetConnection(), and StopReadThread().

Referenced by lldb::SBCommunication::AdoptFileDesriptor(), lldb::SBCommunication::Connect(), lldb_private::ScriptInterpreterIORedirect::ScriptInterpreterIORedirect(), and lldb_private::Process::SetSTDIOFileDescriptor().

◆ SetReadThreadBytesReceivedCallback()

void ThreadedCommunication::SetReadThreadBytesReceivedCallback ( ReadThreadBytesReceived  callback,
void *  callback_baton 
)

◆ StartReadThread()

bool ThreadedCommunication::StartReadThread ( Status error_ptr = nullptr)
virtual

Starts a read thread whose sole purpose it to read bytes from the current connection.

This function will call connection's read function:

size_t Connection::Read (void *, size_t);

When bytes are read and cached, this function will call:

Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);

Subclasses should override this function if they wish to override the default action of caching the bytes and broadcasting a eBroadcastBitReadThreadGotBytes event.

Returns
True if the read thread was successfully started, false otherwise.
See also
size_t Connection::Read (void *, size_t);
void Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);

Definition at line 158 of file ThreadedCommunication.cpp.

References lldb_private::Status::Clear(), lldb_private::Communication, lldb_private::Broadcaster::GetBroadcasterName(), lldb_private::GetLog(), lldb_private::Host, lldb_private::HostThread::IsJoinable(), lldb_private::ThreadLauncher::LaunchThread(), LLDB_LOG, LLDB_LOG_ERROR, m_read_thread, m_read_thread_did_exit, m_read_thread_enabled, m_read_thread_mutex, and ReadThread().

Referenced by lldb::SBCommunication::ReadThreadStart(), lldb_private::ScriptInterpreterIORedirect::ScriptInterpreterIORedirect(), and lldb_private::Process::SetSTDIOFileDescriptor().

◆ StopReadThread()

bool ThreadedCommunication::StopReadThread ( Status error_ptr = nullptr)
virtual

◆ SynchronizeWithReadThread()

void ThreadedCommunication::SynchronizeWithReadThread ( )

Wait for the read thread to process all outstanding data.

After this function returns, the read thread has processed all data that has been waiting in the Connection queue.

Definition at line 351 of file ThreadedCommunication.cpp.

References lldb_private::Communication::m_connection_sp, m_read_thread_did_exit, m_read_thread_enabled, m_synchronize_mutex, and lldb_private::Listener::MakeListener().

Referenced by lldb_private::Process::ShouldBroadcastEvent().

Member Data Documentation

◆ m_bytes

std::string lldb_private::ThreadedCommunication::m_bytes
protected

A buffer to cache bytes read in the ReadThread function.

Definition at line 243 of file ThreadedCommunication.h.

Referenced by AppendBytesToCache(), and GetCachedBytes().

◆ m_bytes_mutex

std::recursive_mutex lldb_private::ThreadedCommunication::m_bytes_mutex
protected

A mutex to protect multi-threaded access to the cached bytes.

Definition at line 244 of file ThreadedCommunication.h.

Referenced by AppendBytesToCache(), and GetCachedBytes().

◆ m_callback

ReadThreadBytesReceived lldb_private::ThreadedCommunication::m_callback
protected

◆ m_callback_baton

void* lldb_private::ThreadedCommunication::m_callback_baton
protected

◆ m_pass_error

Status lldb_private::ThreadedCommunication::m_pass_error
protected

Error passthrough from read thread.

Definition at line 248 of file ThreadedCommunication.h.

Referenced by Read(), and ReadThread().

◆ m_pass_status

lldb::ConnectionStatus lldb_private::ThreadedCommunication::m_pass_status
protected

Connection status passthrough from read thread.

Definition at line 246 of file ThreadedCommunication.h.

Referenced by Read(), and ReadThread().

◆ m_read_thread

HostThread lldb_private::ThreadedCommunication::m_read_thread
protected

The read thread handle in case we need to cancel the thread.

Definition at line 228 of file ThreadedCommunication.h.

Referenced by JoinReadThread(), StartReadThread(), and StopReadThread().

◆ m_read_thread_did_exit

std::atomic<bool> lldb_private::ThreadedCommunication::m_read_thread_did_exit
protected

Whether the read thread is enabled.

Technically this could be guarded by the read thread mutex but that needlessly complicates things to check this variables momentary value.

Definition at line 240 of file ThreadedCommunication.h.

Referenced by Disconnect(), Read(), ReadThread(), StartReadThread(), and SynchronizeWithReadThread().

◆ m_read_thread_enabled

std::atomic<bool> lldb_private::ThreadedCommunication::m_read_thread_enabled
protected

Whether the read thread is enabled.

This cannot be guarded by the read thread mutex becuase it is used as the control variable to exit the read thread.

Definition at line 235 of file ThreadedCommunication.h.

Referenced by Disconnect(), Read(), ReadThread(), ReadThreadIsRunning(), StartReadThread(), StopReadThread(), and SynchronizeWithReadThread().

◆ m_read_thread_mutex

std::mutex lldb_private::ThreadedCommunication::m_read_thread_mutex
protected

Definition at line 229 of file ThreadedCommunication.h.

Referenced by JoinReadThread(), StartReadThread(), and StopReadThread().

◆ m_synchronize_mutex

std::mutex lldb_private::ThreadedCommunication::m_synchronize_mutex
protected

Definition at line 249 of file ThreadedCommunication.h.

Referenced by ReadThread(), and SynchronizeWithReadThread().


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