Warn on unused return values in guidance code, resolves #2686.

https://github.com/Project-OSRM/osrm-backend/pull/2685/files

fixes an issue where we did

    elongate(fstStep, sndStep);

instead of

    newStep = elongate(fstStep, sndStep);

we didn't get any warnings.

The only way to trigger a warning here is to use

```cpp
__attribute__((warn_unused_result))
```

This changeset does exactly that: for the new guidance code prone to
these kind of issue we add such an attribute to the declaration.

include/engine/guidance/lane_processing.hpp

@@ -4,6 +4,7 @@
 #include <vector>
 
 #include "engine/guidance/route_step.hpp"
+#include "util/attributes.hpp"
 
 namespace osrm
 {
@@ -17,10 +18,12 @@ namespace guidance
 // we anticipate lane changes emitting only matching lanes early on.
 // the second parameter describes the duration that we feel two segments need to be apart to count
 // as separate maneuvers.
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> anticipateLaneChange(std::vector<RouteStep> steps,
                                             const double min_duration_needed_for_lane_change = 15);
 
 // Remove all lane information from roundabouts. See #2626.
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> removeLanesFromRoundabouts(std::vector<RouteStep> steps);
 
 } // namespace guidance

include/engine/guidance/post_processing.hpp

@@ -4,6 +4,7 @@
 #include "engine/guidance/leg_geometry.hpp"
 #include "engine/guidance/route_step.hpp"
 #include "engine/phantom_node.hpp"
+#include "util/attributes.hpp"
 
 #include <vector>
 
@@ -15,6 +16,7 @@ namespace guidance
 {
 
 // passed as none-reference to modify in-place and move out again
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> postProcess(std::vector<RouteStep> steps);
 
 // Multiple possible reasons can result in unnecessary/confusing instructions
@@ -22,6 +24,7 @@ std::vector<RouteStep> postProcess(std::vector<RouteStep> steps);
 // intersection would result in two instructions to turn left.
 // Collapsing such turns into a single turn instruction, we give a clearer
 // set of instructionst that is not cluttered by unnecessary turns/name changes.
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> collapseTurns(std::vector<RouteStep> steps);
 
 // trim initial/final segment of very short length.
@@ -32,15 +35,18 @@ std::vector<RouteStep> collapseTurns(std::vector<RouteStep> steps);
 void trimShortSegments(std::vector<RouteStep> &steps, LegGeometry &geometry);
 
 // assign relative locations to depart/arrive instructions
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> assignRelativeLocations(std::vector<RouteStep> steps,
                                                const LegGeometry &geometry,
                                                const PhantomNode &source_node,
                                                const PhantomNode &target_node);
 
 // collapse suppressed instructions remaining into intersections array
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> buildIntersections(std::vector<RouteStep> steps);
 
 // remove steps invalidated by post-processing
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> removeNoTurnInstructions(std::vector<RouteStep> steps);
 
 // remove use lane information that is not actually a turn. For post-processing, we need to
@@ -50,6 +56,7 @@ std::vector<RouteStep> removeNoTurnInstructions(std::vector<RouteStep> steps);
 // FIXME this is currently only a heuristic. We need knowledge on which lanes actually might become
 // turn lanes. If a straight lane becomes a turn lane, this might be something to consider. Right
 // now we bet on lane-anticipation to catch this.
+OSRM_ATTR_WARN_UNUSED
 std::vector<RouteStep> collapseUseLane(std::vector<RouteStep> steps);
 
 // postProcess will break the connection between the leg geometry
@@ -57,6 +64,7 @@ std::vector<RouteStep> collapseUseLane(std::vector<RouteStep> steps);
 // between routing maneuvers and the route steps itself.
 // If required, we can get both in sync again using this function.
 // Move in LegGeometry for modification in place.
+OSRM_ATTR_WARN_UNUSED
 LegGeometry resyncGeometry(LegGeometry leg_geometry, const std::vector<RouteStep> &steps);
 
 } // namespace guidance

include/extractor/guidance/intersection_generator.hpp

@@ -5,6 +5,7 @@
 #include "extractor/guidance/intersection.hpp"
 #include "extractor/query_node.hpp"
 #include "extractor/restriction_map.hpp"
+#include "util/attributes.hpp"
 #include "util/name_table.hpp"
 #include "util/node_based_graph.hpp"
 #include "util/typedefs.hpp"
@@ -46,6 +47,7 @@ class IntersectionGenerator
     // node reached
     // from `from_node` via `via_eid`
     // The resulting candidates have to be analysed for their actual instructions later on.
+    OSRM_ATTR_WARN_UNUSED
     Intersection getConnectedRoads(const NodeID from_node, const EdgeID via_eid) const;
 
     // Merge segregated roads to omit invalid turns in favor of treating segregated roads as
@@ -59,6 +61,7 @@ class IntersectionGenerator
     //
     // The treatment results in a straight turn angle of 180º rather than a turn angle of approx
     // 160
+    OSRM_ATTR_WARN_UNUSED
     Intersection mergeSegregatedRoads(Intersection intersection) const;
 };
 

include/extractor/guidance/motorway_handler.hpp

@@ -5,6 +5,7 @@
 #include "extractor/guidance/intersection_handler.hpp"
 #include "extractor/query_node.hpp"
 
+#include "util/attributes.hpp"
 #include "util/name_table.hpp"
 #include "util/node_based_graph.hpp"
 
@@ -40,11 +41,17 @@ class MotorwayHandler : public IntersectionHandler
                             Intersection intersection) const override final;
 
   private:
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleSliproads(const NodeID intersection_node_id,
                                  Intersection intersection) const;
+
+    OSRM_ATTR_WARN_UNUSED
     Intersection fromMotorway(const EdgeID via_edge, Intersection intersection) const;
+
+    OSRM_ATTR_WARN_UNUSED
     Intersection fromRamp(const EdgeID via_edge, Intersection intersection) const;
 
+    OSRM_ATTR_WARN_UNUSED
     Intersection fallback(Intersection intersection) const;
 };
 

include/extractor/guidance/toolkit.hpp

@@ -1,6 +1,7 @@
 #ifndef OSRM_GUIDANCE_TOOLKIT_HPP_
 #define OSRM_GUIDANCE_TOOLKIT_HPP_
 
+#include "util/attributes.hpp"
 #include "util/bearing.hpp"
 #include "util/coordinate.hpp"
 #include "util/coordinate_calculation.hpp"
@@ -262,6 +263,7 @@ inline bool requiresNameAnnounced(const std::string &from,
 // To simplify handling of Left/Right hand turns, we can mirror turns and write an intersection
 // handler only for one side. The mirror function turns a left-hand turn in a equivalent right-hand
 // turn and vice versa.
+OSRM_ATTR_WARN_UNUSED
 inline ConnectedRoad mirror(ConnectedRoad road)
 {
     const constexpr DirectionModifier::Enum mirrored_modifiers[] = {DirectionModifier::UTurn,
@@ -311,6 +313,7 @@ inline bool hasRoundaboutType(const TurnInstruction instruction)
 // will be corrected to left|throught, since the final lane is not drivable.
 // This is in contrast to a situation with lanes:psv:forward=0 (or not set) where left|through|
 // represents left|through|through
+OSRM_ATTR_WARN_UNUSED
 inline std::string
 trimLaneString(std::string lane_string, std::int32_t count_left, std::int32_t count_right)
 {
@@ -357,6 +360,7 @@ trimLaneString(std::string lane_string, std::int32_t count_left, std::int32_t co
 // turn:lanes=left|through|through|right
 // vehicle:lanes=yes|yes|no|yes
 // bicycle:lanes=yes|no|designated|yes
+OSRM_ATTR_WARN_UNUSED
 inline std::string applyAccessTokens(std::string lane_string, const std::string &access_tokens)
 {
     typedef boost::tokenizer<boost::char_separator<char>> tokenizer;

include/extractor/guidance/turn_handler.hpp

@@ -5,6 +5,7 @@
 #include "extractor/guidance/intersection_handler.hpp"
 #include "extractor/query_node.hpp"
 
+#include "util/attributes.hpp"
 #include "util/name_table.hpp"
 #include "util/node_based_graph.hpp"
 
@@ -46,15 +47,19 @@ class TurnHandler : public IntersectionHandler
                         const ConnectedRoad &road,
                         const ConnectedRoad &other) const;
     // Dead end.
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleOneWayTurn(Intersection intersection) const;
 
     // Mode Changes, new names...
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleTwoWayTurn(const EdgeID via_edge, Intersection intersection) const;
 
     // Forks, T intersections and similar
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleThreeWayTurn(const EdgeID via_edge, Intersection intersection) const;
 
     // Handling of turns larger then degree three
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleComplexTurn(const EdgeID via_edge, Intersection intersection) const;
 
     void
@@ -64,9 +69,12 @@ class TurnHandler : public IntersectionHandler
     std::pair<std::size_t, std::size_t> findFork(const EdgeID via_edge,
                                                  const Intersection &intersection) const;
 
+    OSRM_ATTR_WARN_UNUSED
     Intersection assignLeftTurns(const EdgeID via_edge,
                                  Intersection intersection,
                                  const std::size_t starting_at) const;
+
+    OSRM_ATTR_WARN_UNUSED
     Intersection assignRightTurns(const EdgeID via_edge,
                                   Intersection intersection,
                                   const std::size_t up_to) const;

include/extractor/guidance/turn_lane_augmentation.hpp

@@ -3,6 +3,7 @@
 
 #include "extractor/guidance/intersection.hpp"
 #include "extractor/guidance/turn_lane_data.hpp"
+#include "util/attributes.hpp"
 
 namespace osrm
 {
@@ -13,6 +14,7 @@ namespace guidance
 namespace lanes
 {
 
+OSRM_ATTR_WARN_UNUSED
 LaneDataVector handleNoneValueAtSimpleTurn(LaneDataVector lane_data,
                                            const Intersection &intersection);
 

include/extractor/guidance/turn_lane_data.hpp

@@ -2,6 +2,7 @@
 #define OSRM_EXTRACTOR_GUIDANCE_TURN_LANE_DATA_HPP_
 
 #include "extractor/guidance/turn_lane_types.hpp"
+#include "util/attributes.hpp"
 #include "util/typedefs.hpp"
 #include <string>
 #include <vector>
@@ -26,6 +27,7 @@ struct TurnLaneData
 typedef std::vector<TurnLaneData> LaneDataVector;
 
 // convertes a string given in the OSM format into a TurnLaneData vector
+OSRM_ATTR_WARN_UNUSED
 LaneDataVector laneDataFromDescription(const TurnLaneDescription &turn_lane_description);
 
 // Locate A Tag in a lane data vector (if multiple tags are set, the first one found is returned)

include/extractor/guidance/turn_lane_handler.hpp

@@ -8,6 +8,7 @@
 #include "extractor/guidance/turn_lane_types.hpp"
 #include "extractor/query_node.hpp"
 
+#include "util/attributes.hpp"
 #include "util/guidance/turn_lanes.hpp"
 #include "util/name_table.hpp"
 #include "util/node_based_graph.hpp"
@@ -41,6 +42,7 @@ class TurnLaneHandler
                     const std::vector<QueryNode> &node_info_list,
                     const TurnAnalysis &turn_analysis);
 
+    OSRM_ATTR_WARN_UNUSED
     Intersection assignTurnLanes(const NodeID at,
                                  const EdgeID via_edge,
                                  Intersection intersection,
@@ -60,17 +62,20 @@ class TurnLaneHandler
                               const Intersection &intersection) const;
 
     // in case of a simple intersection, assign the lane entries
+    OSRM_ATTR_WARN_UNUSED
     Intersection simpleMatchTuplesToTurns(Intersection intersection,
                                           const LaneDataVector &lane_data,
                                           const LaneDescriptionID lane_string_id,
                                           LaneDataIdMap &id_map) const;
 
     // partition lane data into lane data relevant at current turn and at next turn
+    OSRM_ATTR_WARN_UNUSED
     std::pair<TurnLaneHandler::LaneDataVector, TurnLaneHandler::LaneDataVector> partitionLaneData(
         const NodeID at, LaneDataVector turn_lane_data, const Intersection &intersection) const;
 
     // if the current intersections turn string is empty, we check whether there is an incoming
     // intersection whose turns might be related to this current intersection
+    OSRM_ATTR_WARN_UNUSED
     Intersection handleTurnAtPreviousIntersection(const NodeID at,
                                                   const EdgeID via_edge,
                                                   Intersection intersection,

include/extractor/guidance/turn_lane_matcher.hpp

@@ -6,6 +6,7 @@
 #include "extractor/guidance/turn_instruction.hpp"
 #include "extractor/guidance/turn_lane_data.hpp"
 
+#include "util/attributes.hpp"
 #include "util/guidance/turn_lanes.hpp"
 #include "util/node_based_graph.hpp"
 
@@ -37,6 +38,7 @@ findBestMatchForReverse(const TurnLaneType::Mask &leftmost_tag, const Intersecti
 bool canMatchTrivially(const Intersection &intersection, const LaneDataVector &lane_data);
 
 // perform a trivial match on the turn lanes
+OSRM_ATTR_WARN_UNUSED
 Intersection triviallyMatchLanesToTurns(Intersection intersection,
                                         const LaneDataVector &lane_data,
                                         const util::NodeBasedDynamicGraph &node_based_graph,

include/util/attributes.hpp

@@ -0,0 +1,15 @@
+#ifndef OSRM_ATTRIBUTES_HPP_
+#define OSRM_ATTRIBUTES_HPP_
+
+
+// OSRM_ATTR_WARN_UNUSED - caller has to use function's return value
+// https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
+
+#if defined(__GNUC__) && (__GNUC__ >= 4)
+  #define OSRM_ATTR_WARN_UNUSED __attribute__ ((warn_unused_result))
+#else
+  #define OSRM_ATTR_WARN_UNUSED
+#endif
+
+
+#endif

include/util/guidance/toolkit.hpp

@@ -6,6 +6,7 @@
 #include "extractor/guidance/turn_instruction.hpp"
 #include "engine/guidance/route_step.hpp"
 #include "engine/phantom_node.hpp"
+#include "util/attributes.hpp"
 #include "util/guidance/bearing_class.hpp"
 #include "util/guidance/entry_class.hpp"
 #include "util/simple_logger.hpp"
@@ -50,6 +51,7 @@ inline extractor::guidance::DirectionModifier::Enum getTurnDirection(const doubl
 }
 
 // swaps left <-> right modifier types
+OSRM_ATTR_WARN_UNUSED
 inline extractor::guidance::DirectionModifier::Enum
 mirrorDirectionModifier(const extractor::guidance::DirectionModifier::Enum modifier)
 {

src/engine/guidance/post_processing.cpp

@@ -5,6 +5,7 @@
 #include "engine/guidance/lane_processing.hpp"
 #include "engine/guidance/toolkit.hpp"
 
+#include "util/attributes.hpp"
 #include "util/guidance/toolkit.hpp"
 #include "util/guidance/turn_lanes.hpp"
 
@@ -127,6 +128,7 @@ double turn_angle(const double entry_bearing, const double exit_bearing)
     return angle > 360 ? angle - 360 : angle;
 }
 
+OSRM_ATTR_WARN_UNUSED
 RouteStep forwardInto(RouteStep destination, const RouteStep &source)
 {
     // Merge a turn into a silent turn
@@ -325,6 +327,7 @@ void closeOffRoundabout(const bool on_roundabout,
 }
 
 // elongate a step by another. the data is added either at the front, or the back
+OSRM_ATTR_WARN_UNUSED
 RouteStep elongate(RouteStep step, const RouteStep &by_step)
 {
     BOOST_ASSERT(step.mode == by_step.mode);