Header File Optimization for ACE Engine

Optimize C++ header file compilation efficiency in ace_engine through systematic dependency reduction and implementation restructuring. This skill focuses on reducing compilation time and memory footprint by minimizing header dependencies and moving implementations out of headers.

When to Use This Skill

Invoke this skill when:

• Optimizing specific header files for compilation efficiency
• Working with test_header.cpp to analyze header dependencies
• Reducing header file dependencies in ace_engine
• Analyzing compilation performance of specific headers
• User specifies "只分析不进行修改" (analysis only, no modifications)

Key Rules

Follow these critical constraints during optimization:

1. Preserve business logic - Only modify structure, not functionality
2. Minimize file creation - Edit current header/cpp directly, only create new files for header splitting scenarios
3. Limit scope - Only perform work defined in key steps, do not expand modification scope
4. Standalone compilation - Use compile-analysis skill for individual file compilation verification, never full build
5. test_header.cpp is read-only - Never modify test_header.cpp; it only serves for dependency statistics

Optimization Workflow

Step 1: Analyze Input and Mode

Determine the optimization target and mode:

• If input is a header file (.h): Optimize that header directly
• If input is test_header.cpp: Extract the header file from its content and optimize that header
• Check if user specified "只分析不进行修改" (analysis only mode)

In analysis-only mode:

• Perform all analysis steps
• Generate optimization recommendations
• Do NOT modify any files
• Present findings and suggested changes for user approval

Step 2: Move Inline Implementations to CPP

Objective: Move all method implementations longer than 3 lines from header to cpp file.

Procedure:

1. Read the target header file
2. Identify all methods (including static methods) with implementations exceeding 3 lines
3. If corresponding cpp file does not exist, create it
4. Move method implementations to cpp file
5. Keep only declarations in header file
6. For template methods, see Step 6

What counts as 3 lines:

// Less than 3 lines - Keep in header
int GetValue() const { return value_; }

// 3 lines or more - Move to cpp
void ProcessData() {
    auto result = Calculate();
    Validate(result);
    cache_.Store(result);
}

Exception: Simple getters/setters that are one-liners typically remain in headers for performance.

Step 3: Remove Unnecessary Header Includes

Objective: Eliminate unused header dependencies.

Procedure:

1. List all #include directives in the header file
2. For each included header, verify if it's actually used:
   • Search for types from that header in the file
   • Check if member variables, function parameters, or return types use those types
   • Verify base class inheritance
3. Remove includes that have no actual usage
4. Document removal reasons in analysis report

Example:

// Before
#include "base/memory/ace_type.h"
#include "core/components/common/layout.h"
#include "core/pipeline/base/element.h"  // Not used - REMOVE

// After
#include "base/memory/ace_type.h"
#include "core/components/common/layout.h"

Step 4: Convert Includes to Forward Declarations

Objective: Replace full header includes with forward declarations wherever possible.

Procedure:

1. For each remaining header include, analyze what's needed from it:
   • Type names only (pointers, references, function parameters)
   • Type definitions (complete class definition needed)
   • Static constants or enums
2. Convert to forward declaration when only type name is needed:

   // Before
   #include "core/components_ng/base/frame_node.h"
   
   // After
   namespace OHOS::Ace::NG {
   class FrameNode;
   }  // namespace OHOS::Ace::NG
   

3. Keep full include only when:
   • Inheriting from the class
   • Class has member variables of that type
   • Template instantiation requires complete definition
   • Accessing static constants or inline methods

Forward Declaration Template:

namespace OHOS::Ace {
namespace NG {
class FrameNode;
class UINode;
}  // namespace NG
}  // namespace OHOS

Step 4.1: Advanced Forward Declaration Scenarios

IMPORTANT: This section contains advanced forward declaration patterns based on real optimization cases in ace_engine.

Scenario 1: Smart Pointer Template Parameters (RefPtr/WeakPtr)

When to use forward declaration:

• Type is only used as template parameter for RefPtr<T> or WeakPtr<T>
• Type is used as member variable with smart pointer
• Type is used as function parameter/return value with smart pointer

Rule: Smart pointer templates (RefPtr, WeakPtr, std::unique_ptr, std::shared_ptr) do NOT require complete type definition in header files.

Example - Before Optimization:

// click_event.h (BEFORE)
#include "core/components_ng/gestures/recognizers/click_recognizer.h"  // ❌ Full include

class ClickEventActuator {
private:
    RefPtr<ClickRecognizer> clickRecognizer_;  // Only needs forward declaration

    const RefPtr<ClickRecognizer>& GetClickRecognizer();  // Also OK with forward decl
};

Example - After Optimization:

// click_event.h (AFTER)
// Removed: #include "click_recognizer.h"
namespace OHOS::Ace::NG {
class ClickRecognizer;  // ✅ Forward declaration only
}

class ClickEventActuator {
private:
    RefPtr<ClickRecognizer> clickRecognizer_;  // Works with forward decl
};

// click_event.cpp
#include "core/components_ng/gestures/recognizers/click_recognizer.h"  // Full include here

const RefPtr<ClickRecognizer>& ClickEventActuator::GetClickRecognizer() {
    if (!clickRecognizer_) {
        clickRecognizer_ = MakeRefPtr<ClickRecognizer>();  // Needs full definition
    }
    return clickRecognizer_;
}

Key Insights:

• ✅ Member variables with RefPtr<T> work with forward declaration
• ✅ Return types const RefPtr<T>& work with forward declaration
• ❌ Actual instantiation MakeRefPtr<T>() requires full definition in .cpp

Verification: Compile both header and cpp to ensure no undefined type errors.

---

Scenario 2: Cross-Namespace Forward Declarations

When to use: When a type from one namespace is needed in another namespace's header file.

Pattern: Add forward declarations in appropriate namespace scope.

Example - gesture_event_hub.h needs ClickInfo:

// click_event.h
#include "base/memory/ace_type.h"
#include "core/components_ng/event/gesture_event_actuator.h"
#include "ui/gestures/gesture_event.h"         // Provides GestureEvent, GestureEventFunc
#include "core/components_ng/event/target_component.h"  // Provides GestureJudgeFunc

// Cross-namespace forward declaration for gesture_event_hub.h
namespace OHOS::Ace {
class ClickInfo;  // Type defined in OHOS::Ace, needed by gesture_event_hub.h
}

namespace OHOS::Ace::NG {
class GestureEventHub;   // Forward declaration in target namespace
class ClickRecognizer;   // Forward declaration in target namespace
}

class ClickEventActuator : public GestureEventActuator {
    // ... implementation
};

Why this works:

• When gesture_event_hub.h is included through frame_node.h → click_event.h chain
• ClickInfo forward declaration is already available
• Avoids circular dependencies
• Reduces coupling between namespaces

---

Scenario 3: Replacing Indirect Dependencies with Precise Includes

Problem: Removing a heavy include (like click_recognizer.h) breaks compilation because other types were indirectly included.

Solution: Identify and directly include only the necessary type definition headers.

Example - Removing click_recognizer.h:

// BEFORE: Heavy indirect dependencies
#include "core/components_ng/gestures/recognizers/click_recognizer.h"
// This indirectly brought in:
// - tap_gesture.h (GestureEventFunc)
// - gesture_recognizer.h
// - multi_fingers_recognizer.h
// - And many more...

// AFTER: Precise includes
#include "ui/gestures/gesture_event.h"         // Provides GestureEvent, GestureEventFunc
#include "core/components_ng/event/target_component.h"  // Provides GestureJudgeFunc

// Forward declarations
namespace OHOS::Ace::NG {
class ClickRecognizer;  // Only name needed for RefPtr<ClickRecognizer>
}

Analysis Process:

1. Search for type usages in the header (e.g., GestureEventFunc, GestureJudgeFunc)
2. Find their definition locations using grep/search tools
3. Include the header that defines the type directly
4. Replace heavy include with forward declaration for RefPtr/WeakPtr types

---

Scenario 4: Complete Decision Matrix for Forward Declarations

Usage Pattern	Can Use Forward Decl?	Requires Full Include?
T* member variable	✅ Yes	❌ No
T& parameter/return	✅ Yes	❌ No
RefPtr<T> member	✅ Yes	❌ No
RefPtr<T>& return	✅ Yes	❌ No
WeakPtr<T> member	✅ Yes	❌ No
std::unique_ptr<T>	✅ Yes	❌ No
std::shared_ptr<T>	✅ Yes	❌ No
std::vector<T>	❌ No*	✅ Yes
std::vector<T*>	✅ Yes	❌ No
Class inheritance	❌ No	✅ Yes
T member variable	❌ No	✅ Yes
T value parameter	❌ No*	✅ Yes
Template instantiation	❌ No	✅ Yes
Access static members	❌ No	✅ Yes
Access inline methods	❌ No	✅ Yes

* Exceptions exist with extern templates

---

Common Pitfalls and Solutions

Pitfall 1: Removing include breaks dependent headers

Symptom:

error: unknown type name 'ClickInfo' in gesture_event_hub.h

Root Cause: gesture_event_hub.h was indirectly getting ClickInfo from click_recognizer.h

Solution: Add forward declaration in appropriate namespace

namespace OHOS::Ace {
class ClickInfo;  // Forward declaration for gesture_event_hub.h
}

---

Pitfall 2: Missing type definitions after removing include

Symptom:

error: unknown type name 'GestureEventFunc'
error: unknown type name 'GestureJudgeFunc'

Root Cause: These types were indirectly included through click_recognizer.h

Solution: Directly include headers that define these types

#include "ui/gestures/gesture_event.h"         // GestureEvent, GestureEventFunc
#include "core/components_ng/event/target_component.h"  // GestureJudgeFunc

---

Pitfall 3: Namespace mismatch in forward declarations

Symptom:

error: no type named 'ClickInfo' in namespace 'OHOS::Ace::NG'

Root Cause: ClickInfo is in OHOS::Ace, not OHOS::Ace::NG

Solution: Use correct namespace for forward declaration

namespace OHOS::Ace {        // Correct namespace
class ClickInfo;
}

namespace OHOS::Ace::NG {    // Different namespace
class ClickRecognizer;
}

---

Real Case Study: click_event.h Optimization

Before Optimization:

// 214 lines, 6 includes
#include <list>
#include "base/memory/ace_type.h"
#include "base/memory/referenced.h"              // Redundant
#include "base/utils/noncopyable.h"
#include "core/components_ng/event/gesture_event_actuator.h"
#include "core/components_ng/gestures/recognizers/click_recognizer.h"  // Heavy include

namespace OHOS::Ace::NG {
class GestureEventHub;  // Only 1 forward declaration
}

// 15 inline method implementations

After Optimization:

// 139 lines (-35%), 5 includes (-16.7%)
#include <list>
#include "base/memory/ace_type.h"
#include "base/utils/noncopyable.h"
#include "core/components_ng/event/gesture_event_actuator.h"
#include "ui/gestures/gesture_event.h"         // Precise include
#include "core/components_ng/event/target_component.h"  // Precise include

namespace OHOS::Ace {
class ClickInfo;  // Cross-namespace forward declaration
}

namespace OHOS::Ace::NG {
class GestureEventHub;    // Existing forward declaration
class ClickRecognizer;    // ✨ New forward declaration (RefPtr<T> optimization)
}

// 5 inline method implementations (moved 12 to cpp)

Results:

• ✅ Header reduced from 214 to 139 lines (-35.0%)
• ✅ Includes reduced from 6 to 5 (-16.7%)
• ✅ Forward declarations increased from 1 to 3 (+200%)
• ✅ Inline implementations reduced from 15 to 5 (-66.7%)
• ✅ Compilation verified successfully
• ✅ test_header.cpp indirect dependency verified

Key Techniques Applied:

1. Replaced #include "click_recognizer.h" with forward declaration
2. Added precise includes for type definitions (GestureEventFunc, GestureJudgeFunc)
3. Added cross-namespace forward declaration for ClickInfo
4. Moved 12 inline implementations to cpp file

---

Step 5: Split Headers for Constants and Enums

Objective: Extract frequently-used constants or enums into separate headers to reduce coupling.

When to Apply:

• Original header is only included for a few constants or enum values
• Multiple files depend on these constants but not the full header
• Splitting provides measurable compilation benefit

Procedure:

1. Identify constants or enums that are dependencies for other files
2. Create new header file (e.g., original_types.h, original_constants.h)
3. Move extracted definitions to new header
4. Update original header to include the split header
5. Update dependent files to include only the smaller header

Example:

// original.h (before)
#pragma once
namespace Constants {
    constexpr int MAX_VALUE = 100;
    enum class Type { A, B, C };
}

class BigImplementation {
    // ... hundreds of lines
};

// original_types.h (after split)
#pragma once
namespace Constants {
    constexpr int MAX_VALUE = 100;
    enum class Type { A, B, C };
}

// original.h (after split)
#pragma once
#include "original_types.h"
class BigImplementation {
    // ... implementation
};

Verification: Only split if it provides clear compilation benefit. Measure before/after with compile-analysis skill.

Step 6: Apply PIMPL Pattern (When Applicable)

Objective: Hide implementation details to reduce compilation dependencies.

When to Apply:

• Header has many heavy dependencies from private members
• Public API is stable but implementation changes frequently
• Reducing header dependencies would significantly improve compile time

Procedure:

1. Create an Impl class (forward declared in header)
2. Move private members and heavy dependencies to Impl class in cpp
3. Replace private members with std::unique_ptr
4. Update constructor/destructor to manage Impl lifecycle

PIMPL Template:

// header.h
#pragma once
#include <memory>
namespace OHOS::Ace {
class MyClass {
public:
    MyClass();
    ~MyClass();

    // Public interface
    void PublicMethod();

private:
    class Impl;
    std::unique_ptr<Impl> impl_;
};

// cpp.cpp
#include "header.h"
#include "heavy_dependency.h"

class MyClass::Impl {
public:
    HeavyDependency dep_;
    // Private implementation details
};

MyClass::MyClass() : impl_(std::make_unique<Impl>()) {}
MyClass::~MyClass() = default;

void MyClass::PublicMethod() {
    impl_->dep_.DoSomething();
}

Caution: PIMPL adds runtime overhead (extra allocation, indirection). Only use when compilation benefit justifies cost.

Step 7: Optimize Template Methods

Objective: Reduce template compilation overhead through explicit instantiation.

Procedure:

1. Identify template methods in header
2. Check if templates can be converted to regular methods with explicit instantiation
3. Move template implementations to cpp file
4. Add explicit instantiation declarations for commonly used types

Example:

// header.h (before)
template<typename T>
void Process(T value) {
    // Implementation
}

// header.h (after)
template<typename T>
void Process(T value);

extern template void Process<int>(int);
extern template void Process<float>(float);

// cpp.cpp (after)
template<typename T>
void Process(T value) {
    // Implementation
}

template void Process<int>(int);
template void Process<float>(float);

Limitation: Only works when template parameter types are known and limited.

Step 8: Verify Standalone Compilation

Objective: Ensure optimized code compiles correctly.

Procedure:

1. Use compile-analysis skill to extract compilation command for the cpp file
2. Verify standalone compilation of the cpp file
3. For test_header.cpp analysis, verify it compiles with optimized header
4. Do NOT run full build - only standalone compilation verification

Error Handling:

• If compilation fails, analyze errors
• Fix missing includes or forward declarations
• Re-verify until compilation succeeds
• Document all fixes applied

Step 9: Measure Optimization Results

Objective: Quantify the impact of optimizations.

Metrics to Collect:

1. Header dependency count:

   • Count includes before optimization
   • Count includes after optimization
   • Calculate reduction percentage

2. Compilation time:

   • Use compile-analysis skill to measure before/after
   • Report time savings

3. Memory footprint:

   • Measure header file size before/after
   • Report reduction percentage

4. Lines of code:

   • Header file LOC reduction
   • New LOC added to cpp file

Result Template:

## Optimization Results

### Header: frameworks/path/to/header.h

**Before Optimization:**
- Includes: 15
- Header size: 45.2 KB
- Estimated compile impact: High

**After Optimization:**
- Includes: 6
- Header size: 12.8 KB
- Reduction: 60% includes, 72% size

**Changes Made:**
- Moved 12 method implementations to cpp
- Converted 8 includes to forward declarations
- Removed 3 unused includes
- Split constants into separate header
- Applied PIMPL pattern (if applicable)

**Compilation Status:** ✅ Verified standalone compilation

Step 10: Stage Changes with Git

Objective: Preserve optimized files in git.

Procedure:

1. Use git add to stage modified files:
   • Optimized header file
   • Modified or created cpp file
   • Any newly created split headers
2. Do NOT stage test_header.cpp (it's reference only)
3. Present staged changes to user

---

Generalized Optimization Strategies

This section provides generalized guidance derived from real optimization cases in ace_engine. Use these strategies to select the right optimization approach for your situation.

Strategy Selection Decision Tree

┌─────────────────────────────────────────────────────────────┐
│               What type of dependency problem?              │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   Heavy include        Value type        Cross-namespace
   within same        member from        include with
   namespace          heavy include    only enum usage
        │                   │                   │
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  RefPtr<T>    │  │ unique_ptr<T> │  │ Light Include │
│  Forward Decl │  │  + Forward    │  │  Replacement │
│  (Scenario 1) │  │  Declaration  │  │  (Scenario 3) │
└───────────────┘  └───────────────┘  └───────────────┘

Scenario 1: RefPtr Forward Declaration (Lightest)

When to use:

• Member is already RefPtr<T> or WeakPtr<T>
• Only type name needed in header
• No value semantics required

Pattern:

// Header
namespace OHOS::Ace::NG {
class ClickRecognizer;  // Forward declaration
}

class ClickEventActuator {
private:
    RefPtr<ClickRecognizer> clickRecognizer_;  // ✅ Works with forward decl
};

// CPP
#include "core/components_ng/gestures/recognizers/click_recognizer.h"

const RefPtr<ClickRecognizer>& ClickEventActuator::GetClickRecognizer() {
    if (!clickRecognizer_) {
        clickRecognizer_ = MakeRefPtr<ClickRecognizer>();  // Full definition needed here
    }
    return clickRecognizer_;
}

⚠️ CRITICAL: RefPtr Members CAN Use Forward Declarations

Common misconception: "RefPtr members require complete type definition"

✅ Correct understanding: RefPtr members work perfectly with forward declarations, provided that:

1. All inline methods that use the RefPtr member are moved to .cpp

   • Any method that calls member_->Method() must be in .cpp
   • Any method that calls MakeRefPtr<T>() must be in .cpp
   • Any method with RefPtr<T> parameter or return type should be in .cpp

2. Only declarations remain in header

   • RefPtr<T> member_; ✅ Works with forward declaration
   • RefPtr<T> GetMember(); ✅ Declaration only
   • void SetMember(const RefPtr<T>& member); ✅ Declaration only

3. No inline instantiation in header

   • ❌ MakeRefPtr<T>() calls in header
   • ❌ member_->Method() calls in header
   • ✅ Both must be in .cpp implementation

Example from gesture_recognizer.h optimization:

// gesture_recognizer.h - BEFORE (inline implementations)
class NGGestureRecognizer {
    bool IsSystemGesture() const {  // ❌ Inline - needs full GestureInfo definition
        if (!gestureInfo_) return false;
        return gestureInfo_->IsSystemGesture();
    }

    RefPtr<GestureInfo> GetGestureInfo() {  // ❌ Inline - returns RefPtr<GestureInfo>
        return gestureInfo_;
    }

private:
    RefPtr<GestureInfo> gestureInfo_;  // ❌ Requires full definition due to inline methods
};

// gesture_recognizer.h - AFTER (forward declaration + declarations)
namespace OHOS::Ace::NG {
class GestureInfo;  // ✅ Forward declaration only
}

class NGGestureRecognizer {
    bool IsSystemGesture() const;  // ✅ Declaration only

    RefPtr<GestureInfo> GetGestureInfo();  // ✅ Declaration only

private:
    RefPtr<GestureInfo> gestureInfo_;  // ✅ Works with forward declaration!
};

// gesture_recognizer.cpp - Full implementations
#include "core/components_ng/event/gesture_info.h"  // ✅ Full include here

bool NGGestureRecognizer::IsSystemGesture() const {
    if (!gestureInfo_) return false;
    return gestureInfo_->IsSystemGesture();  // ✅ Full definition available
}

RefPtr<GestureInfo> NGGestureRecognizer::GetGestureInfo() {
    return gestureInfo_;  // ✅ Can return RefPtr with full definition
}

Key principle: RefPtr members do NOT require complete type definition in the header. The requirement comes from inline methods that use the member, not from the member itself.

Benefits:

• ✅ No destructor separation needed (RefPtr manages lifecycle)
• ✅ Minimal code changes
• ✅ Zero runtime overhead
• ✅ Existing pattern in ace_engine

Real case: case-click_event-forward-declaration.md

Complexity: Easy

---

Scenario 2: Value Type → unique_ptr Conversion

When to use:

• Value type member from heavy include
• Member only used in implementation (.cpp)
• Want to remove heavy include dependency
• Can accept small runtime overhead (heap allocation)

Pattern:

// Before
#include "core/components_ng/gestures/gesture_info.h"  // Heavy include

class DragDropRelatedConfigurations {
private:
    DragPreviewOption previewOption_;  // ❌ Value type - needs full definition
};

// After
namespace OHOS::Ace::NG {
struct DragPreviewOption;  // Forward declaration
}

class DragDropRelatedConfigurations {
public:
    ~DragDropRelatedConfigurations() override;  // ✅ Declaration only

    ACE_FORCE_EXPORT const DragPreviewOption& GetOrCreateDragPreviewOption();  // ✅ Return const&

private:
    std::unique_ptr<DragPreviewOption> previewOption_;  // ✅ Smart pointer
};

// CPP
#include "core/components_ng/gestures/gesture_info.h"  // Full include

DragDropRelatedConfigurations::~DragDropRelatedConfigurations() = default;