Deprecated API Migration

Deprecated API Migration Process

1. Identify deprecated APIs: Check for deprecation warnings during compilation and confirm the replacement APIs.
2. Evaluate the migration impact: Analyze the differences in API parameters, return values, and semantic differences.
3. Write migration code: Replace the deprecated API calls and adapt to the new API parameters.
4. Test and verification: Ensure that the functions are correct and the performance meets expectations after the migration.

Migration Example: aclrtQueryEvent -> aclrtQueryEventStatus

// Deprecated API (old code).
aclrtEventStatus status;
aclrtQueryEvent(event, &status);
if (status == ACL_EVENT_STATUS_COMPLETE) {
    // ...
}

// Replacement API (new code).
aclrtEventRecordedStatus status;
aclrtQueryEventStatus(event, &status);
if (status == ACL_EVENT_RECORDED_STATUS_COMPLETE) {
    // ...
}

Recommended

1. Regularly checking compilation warnings: Handle deprecated API warnings promptly to avoid accumulation.
2. Preferentially using new APIs: New APIs usually have better semantics, performance, or functionality.
3. Recording version information: Record the Runtime version when the application starts, thus facilitating fault locating.
4. Preferring feature detection over versions: Use the feature query API instead of hardcoded version numbers to query capabilities.
5. Encapsulating version adaptation logic: Centralize compatibility logic at the adaptation layer to facilitate maintenance.

Not recommended

1. Ignoring deprecation warnings: Deprecated APIs may be removed in future versions, leading to compilation failures.
2. Hard-coding version checks: Version checking lacks flexibility. Use feature detection instead.
3. Mixing old and new APIs: Use either the new or old APIs consistently within the same functional module to avoid confusion.
4. Assuming that API semantics remain unchanged: During migration, carefully read the new API documentation to ensure semantic consistency.