drifty/comaps
1
0
Fork 0
mirror of https://codeberg.org/comaps/comaps synced 2025-12-19 13:03:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation

Browse Source 
Signed-off-by: mvglasow <michael -at- vonglasow.com>
This commit is contained in:
mvglasow
2025-06-08 20:01:35 +03:00
parent d47713516d
commit b98fe1999c
6 changed files with 168 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
indexer/mwm_set.hpp
View File

@@ -141,8 +141,10 @@ public:
explicit MwmSet(size_t cacheSize = 64) : m_cacheSize(cacheSize) {}
virtual ~MwmSet() = default;
// Mwm handle, which is used to refer to mwm and prevent it from
// deletion when its FileContainer is used.
/**
* @brief Mwm handle, which is used to refer to mwm and prevent it from deletion when its
* FileContainer is used.
*/
class MwmHandle
{
public:
@@ -230,19 +232,26 @@ public:
BadFile
};
// An Observer interface to MwmSet. Note that these functions can
// be called from *ANY* thread because most signals are sent when
// some thread releases its MwmHandle, so overrides must be as fast
// as possible and non-blocking when it's possible.
/**
* @brief An Observer interface to `MwmSet`.
*
* Note that these functions can be called from *ANY* thread because most signals are sent when
* some thread releases its MwmHandle, so overrides must be as fast as possible and non-blocking
* when it's possible.
*/
class Observer
{
public:
virtual ~Observer() = default;
// Called when a map is registered for the first time and can be used.
/**
* @brief Called when a map is registered for the first time and can be used.
*/
virtual void OnMapRegistered(platform::LocalCountryFile const & /* localFile */) {}
// Called when a map is deregistered and can no longer be used.
/**
* @brief Called when a map is deregistered and can no longer be used.
*/
virtual void OnMapDeregistered(platform::LocalCountryFile const & /* localFile */) {}
};
@@ -290,7 +299,14 @@ public:
/// @todo In fact, std::shared_ptr<MwmInfo> is a MwmId. Seems like better to make vector<MwmId> interface.
void GetMwmsInfo(std::vector<std::shared_ptr<MwmInfo>> & info) const;
// Clears caches and mwm's registry. All known mwms won't be marked as DEREGISTERED.
/**
* @brief Clears caches and mwm's registry.
*
* All known mwms won't be marked as DEREGISTERED.
*
* @todo what does “all won’t be marked” mean? Not all will be marked/some might not be marked?
* Or all will be unmarked?
*/
void Clear();
void ClearCache();
@@ -334,10 +350,18 @@ private:
ProcessEventList(events);
}
// Sets |status| in |info|, adds corresponding event to |event|.
/**
* @brief Sets `status` in `info`, adds corresponding event to `event`.
* @param info
* @param status
* @param events
*/
void SetStatus(MwmInfo & info, MwmInfo::Status status, EventList & events);
// Triggers observers on each event in |events|.
/**
* @brief Triggers observers on each event in `events`.
* @param events
*/
void ProcessEventList(EventList & events);
/// @precondition This function is always called under mutex m_lock.

13
map/framework.hpp
View File

@@ -491,11 +491,18 @@ private:
std::unique_ptr<descriptions::Loader> m_descriptionsLoader;
public:
// Moves viewport to the search result and taps on it.
/**
* @brief Moves viewport to the search result and taps on it.
* @param res
* @param animation
*/
void SelectSearchResult(search::Result const & res, bool animation);
// Cancels all searches, stops location follow and then selects
// search result.
/**
* @brief Cancels all searches, stops location follow and then selects search result.
* @param res
* @param animation
*/
void ShowSearchResult(search::Result const & res, bool animation = true);
size_t ShowSearchResults(search::Results const & results);

106
platform/local_country_file.hpp
View File

@@ -13,53 +13,88 @@
namespace platform
{
// This class represents a path to disk files corresponding to some
// country region.
//
// This class also wraps World.mwm and WorldCoasts.mwm
// files from resource bundle, when they can't be found in a data
// directory. In this exceptional case, directory will be empty and
// SyncWithDisk()/DeleteFromDisk()/GetPath()/GetSize() will return
// incorrect results.
//
// In any case, when you're going to read a file LocalCountryFile points to,
// use platform::GetCountryReader().
/**
* @brief Represents a path to disk files corresponding to some country region.
*
* This class also wraps World.mwm and WorldCoasts.mwm files from resource bundle, when they can't
* be found in a data directory. In this exceptional case, directory will be empty and
* `SyncWithDisk()`/`DeleteFromDisk()`/`GetPath()`/`GetSize()` will return incorrect results.
*
* In any case, when you're going to read a file LocalCountryFile points to, use
* `platform::GetCountryReader()`.
*/
class LocalCountryFile
{
public:
LocalCountryFile();
// Creates an instance holding a path to countryFile's in a
// directory. Note that no disk operations are not performed until
// SyncWithDisk() is called.
// The directory must contain a full path to the country file.
/**
* @brief Creates an instance holding a path to countryFile's in a directory.
*
* Note that no disk operations are performed until `SyncWithDisk()` is called.
*
* @param directory full path to the country file
* @param countryFile
* @param version
*/
LocalCountryFile(std::string directory, CountryFile countryFile, int64_t version);
// Syncs internal state like availability of files, their sizes etc. with disk.
// Generality speaking it's not always true. To know it for sure it's necessary to read a mwm in
// this method but it's not implemented by performance reasons. This check is done on
// building routes stage.
/**
* @brief Syncs internal state like availability of files, their sizes etc. with disk.
*
* Generality speaking it's not always true. To know it for sure it's necessary to read a mwm in
* this method but it's not implemented by performance reasons. This check is done on
* building routes stage.
*/
void SyncWithDisk();
// Removes specified file from disk if it is known for LocalCountryFile, i.e.
// it was found by a previous SyncWithDisk() call.
/**
* @brief Deletes a file from disk.
*
* Removes the specified file from disk for `LocalCountryFile`, if it is known, i.e. it was found
* by a previous SyncWithDisk() call.
* @param type
*/
void DeleteFromDisk(MapFileType type) const;
// Returns path to a file.
// Return value may be empty until SyncWithDisk() is called.
/**
* @brief Returns the path to a file.
*
* Return value may be empty until SyncWithDisk() is called.
*
* @param type
* @return
*/
std::string GetPath(MapFileType type) const;
std::string GetFileName(MapFileType type) const;
// Returns size of a file.
// Return value may be zero until SyncWithDisk() is called.
/**
* @brief Returns the size of a file.
*
* Return value may be zero until SyncWithDisk() is called.
*
* @param type
* @return
*/
uint64_t GetSize(MapFileType type) const;
// Returns true when some files are found during SyncWithDisk.
// Return value is false until SyncWithDisk() is called.
/**
* @brief Returns true when files are found during `SyncWithDisk()`.
*
* Return value is false until `SyncWithDisk()` is called.
*
* @return
*/
bool HasFiles() const;
// Checks whether files specified in filesMask are on disk.
// Return value will be false until SyncWithDisk() is called.
/**
* @brief Checks whether files specified in filesMask are on disk.
*
* Return value will be false until SyncWithDisk() is called.
*
* @param type
* @return
*/
bool OnDisk(MapFileType type) const;
bool IsInBundle() const { return m_directory.empty(); }
@@ -74,8 +109,17 @@ public:
bool ValidateIntegrity() const;
// Creates LocalCountryFile for test purposes, for a country region
// with countryFileName (without any extensions). Automatically performs sync with disk.
//
/**
* @brief Creates a `LocalCountryFile` for test purposes.
*
* Creates a `LocalCountryFile` for test purposes, for a country region with `countryFileName`.
* Automatically performs sync with disk.
*
* @param countryFileName The filename, without any extension.
* @param version The data version.
* @return
*/
static LocalCountryFile MakeForTesting(std::string countryFileName, int64_t version = 0);
// Used in generator only to simplify getting instance from path.

9
routing/road_point.hpp
View File

@@ -9,10 +9,11 @@
namespace routing
{
// RoadPoint is a unique identifier for any road point in mwm file.
//
// Contains feature id and point id.
// Point id is the ordinal number of the point in the road.
/**
* @brief A unique identifier for any road point in an mwm file.
*
* It contains a feature id and point id. The point id is the ordinal number of the point in the road.
*/
class RoadPoint final
{
public:

22
routing/segment.hpp
View File

@@ -9,14 +9,16 @@
namespace routing
{
// This is directed road segment used as vertex in index graph.
//
// You can imagine the segment as a material arrow.
// Head of each arrow is connected to fletchings of next arrows with invisible links:
// these are the edges of the graph.
//
// Position of the segment is a position of the arrowhead: GetPointId(true).
// This position is used in heuristic and edges weight calculations.
/**
* @brief A directed road segment used as a vertex in the index graph.
*
* You can imagine the segment as a material arrow.
* Head of each arrow is connected to fletchings of next arrows with invisible links:
* these are the edges of the graph.
*
* Position of the segment is a position of the arrowhead: GetPointId(true).
* This position is used in heuristic and edges weight calculations.
*/
class Segment final
{
public:
@@ -82,7 +84,9 @@ public:
bool operator<(SegmentEdge const & edge) const;
private:
// Target is vertex going to for outgoing edges, vertex going from for ingoing edges.
/**
* @brief Vertex going to for outgoing edges, vertex going from for ingoing edges.
*/
Segment m_target;
RouteWeight m_weight;
};

30
routing_common/num_mwm_id.hpp
View File

@@ -17,11 +17,21 @@ using NumMwmId = std::uint16_t;
NumMwmId constexpr kFakeNumMwmId = std::numeric_limits<NumMwmId>::max();
NumMwmId constexpr kGeneratorMwmId = 0;
/**
* @brief A numbered list of country files.
*/
class NumMwmIds final
{
public:
bool IsEmpty() const { return m_idToFile.empty(); }
/**
* @brief Registers a file, i.e. adds it to the instance.
*
* If the instance already contains the file, this is a no-op.
*
* @param file
*/
void RegisterFile(platform::CountryFile const & file)
{
if (ContainsFile(file))
@@ -34,22 +44,42 @@ public:
//LOG(LDEBUG, ("MWM:", file.GetName(), "=", id));
}
/**
* @brief Whether this instance contains a given file.
* @param file
* @return
*/
bool ContainsFile(platform::CountryFile const & file) const
{
return m_fileToId.find(file) != m_fileToId.cend();
}
/**
* @brief Whether this instance contains a file at a given index.
* @param mwmId The index.
* @return
*/
bool ContainsFileForMwm(NumMwmId mwmId) const
{
return mwmId < m_idToFile.size();
}
/**
* @brief Returns a file by index.
* @param mwmId The index.
* @return
*/
platform::CountryFile const & GetFile(NumMwmId mwmId) const
{
ASSERT_LESS(mwmId, m_idToFile.size(), ());
return m_idToFile[mwmId];
}
/**
* @brief Returns the index for a given file.
* @param file
* @return
*/
NumMwmId GetId(platform::CountryFile const & file) const
{
auto const it = m_fileToId.find(file);