Error Handling

How Plugify deals with runtime issues.

Plugify is designed for maximum performance, which means plugins interact directly with each other without intermediate error-handling mechanisms. This approach ensures minimal overhead but places the responsibility for error handling on plugin developers. This page explains the current approach to error handling and provides recommendations for creating safe and robust exported functions.

Current Approach to Error Handling

Plugify does not currently handle errors at the framework level. This is because plugins load and interact with each other directly to achieve maximum performance. As a result, it is the responsibility of plugin developers to ensure that their exported functions are safe to use, especially when called from other languages.

Key Points

  • No Framework-Level Error Handling: Plugify does not intercept or handle errors that occur during plugin interactions.
  • Direct Plugin Communication: Plugins call each other's functions directly, which means errors must be handled within the plugins themselves.
  • Language-Specific Mechanisms: Some languages, like Python or C#, have built-in exception handling mechanisms that can prevent critical errors and crashes. However, this is not universal across all languages.

Recommendations for Plugin Developers

To ensure that your plugins are robust and safe to use, follow these recommendations when creating exported functions:

Use Return Values to Indicate Errors

For languages without built-in exception handling (e.g., C, Go), use return values to indicate whether a function succeeded or failed. For example:

  • Return a boolean value (true for success, false for failure).
  • Use an enum to provide more detailed error codes.

Example in C++

extern "C" bool SafeFunction(int32_t input, int32_t* output) {
    if (input < 0) {
        return false; // Indicate failure
    }
    *output = input * 2;
    return true; // Indicate success
}

Validate Input Parameters

Always validate input parameters to ensure they are within expected ranges or formats. This prevents crashes caused by invalid data.

Example in Python

def safe_function(input: int) -> int:
    if input < 0:
        raise ValueError("Input must be a non-negative integer")
    return input * 2

Use Language-Specific Mechanisms

For languages with built-in exception handling (e.g., Python, C#), use exceptions to handle errors gracefully. This ensures that critical errors do not crash the application.

Example in C#

public int SafeFunction(int input) {
    if (input < 0) {
        throw new ArgumentException("Input must be a non-negative integer");
    }
    return input * 2;
}

Document Error Conditions

Clearly document the error conditions and return values for your functions. This helps other developers understand how to handle errors when using your plugin.

Example Documentation

/**
 * @brief Multiplies the input by 2.
 *
 * @param input A non-negative integer.
 * @param output Pointer to store the result.
 * @return true if successful, false if input is invalid.
 */
bool SafeFunction(int32_t input, int32_t* output);

Future Improvements

While the current approach prioritizes performance, we recognize the need for a more robust error-handling mechanism in the future. Potential improvements include:

  • Framework-Level Error Handling: Introducing a mechanism to intercept and handle errors at the Plugify level.
  • Error Propagation: Allowing errors to propagate between plugins in a controlled manner.
  • Standardized Error Codes: Defining a set of standard error codes for common issues.

Best Practices for Plugin Developers

  1. Design for Safety: Assume that your functions will be called from other languages and ensure they are safe to use.
  2. Test Thoroughly: Test your plugins with a variety of inputs, including edge cases, to ensure they handle errors gracefully.
  3. Follow Language Conventions: Use the error-handling mechanisms native to your language (e.g., exceptions in Python, return codes in C).
  4. Provide Clear Documentation: Document the error conditions and expected behavior of your functions.

Conclusion

While Plugify currently does not handle errors at the framework level, plugin developers can ensure robust and safe interactions by following the recommendations outlined above. By designing functions with error handling in mind, you can prevent crashes and improve the reliability of your plugins.

In the future, we plan to introduce more efficient error-handling mechanisms to make Plugify even more robust and developer-friendly. Until then, the responsibility lies with plugin developers to create safe and reliable code.

Edit this page on GitHub
Code Style
Coding conventions and guidelines.
Debugging
Guide on diagnosing issues, debugging plugins, and fixing common errors when running Plugify in a Metamod environment.