一个用于触发各种时机的框架。灵感来源于字节跳动内部框架 Gaia，但以不同的方式实现。在希腊神话中，Rhea 是 Gaia 的女儿，因此得名此框架。
在 Swift 5.10 之后，借助 @_used @_section 的支持（可以将数据写入 sections），结合 Swift Macro，我们现在可以实现从 OC 时代开始的各种解耦和注册能力。此框架也已使用这种方法完全重构。
🟡 目前，此功能仍是 Swift 的实验性特性，需要通过配置设置启用。详见集成文档。
XCode 16.0 +
iOS 13.0+, macOS 10.15+, tvOS 13.0+, visionOS 1.0+, watchOS 7.0+
Swift 5.10
swift-syntax 600.0.0
import RheaExtension
#rhea(time: .customEvent, priority: .veryLow, repeatable: true, func: { _ in
print("~~~~ customEvent in main")
})
#rhea(time: .homePageDidAppear, async: true, func: { context in
// This will run on a background thread
print("~~~~ homepageDidAppear")
})
#rhea(time: .load) { _ in
print("load with trailing closure")
}
#load {
print("use load directly")
}
#premain {
print("use premain directly")
}
#appDidFinishLaunching {
print("use appDidFinishLaunching directly")
}
class ViewController: UIViewController {
#load {
print("~~~~ load nested in main")
}
#rhea(time: .homePageDidAppear) { context in
print("homePageDidAppear with trailing closure \(context.param)")
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Rhea.trigger(event: .homePageDidAppear, param: self)
}
}
该框架提供三个回调时机
- OC + load
- constructor (premain)
- appDidFinishLaunching ()
这三个时机由框架内部触发，无需外部触发调用。
此外，用户可以自定义时机和触发器，配置相同时机的执行优先级，以及是否可以重复执行。
/// Registers a callback function for a specific Rhea event.
///
/// This macro is used to register a callback function to a section in the binary,
/// associating it with a specific event time, priority, and repeatability.
///
/// - Parameters:
/// - time: A `RheaEvent` representing the timing or event name for the callback.
/// This parameter also supports direct string input, which will be
/// processed by the framework as an event identifier.
/// - priority: A `RheaPriority` value indicating the execution priority of the callback.
/// Default is `.normal`. Predefined values include `.veryLow`, `.low`,
/// `.normal`, `.high`, and `.veryHigh`. Custom integer priorities are also
/// supported. Callbacks for the same event are sorted and executed based
/// on this priority.
/// - repeatable: A boolean flag indicating whether the callback can be triggered multiple times.
/// If `false` (default), the callback will only be executed once.
/// If `true`, the callback can be re-triggered on subsequent event occurrences.
/// - async: A boolean flag indicating whether the callback should be executed asynchronously.
/// If `false` (default), the callback will be executed on the main thread.
/// If `true`, the callback will be executed on a background thread. Note that when
/// `async` is `true`, the execution order based on `priority` may not be guaranteed.
/// Even when `async` is set to `false`, users can still choose to dispatch their tasks
/// to a background queue within the callback function if needed. This provides
/// flexibility for handling both quick, main thread operations and longer-running
/// background tasks.
/// - func: The callback function of type `RheaFunction`. This function receives a `RheaContext`
/// parameter, which includes `launchOptions` and an optional `Any?` parameter.
///
/// - Note: When triggering an event externally using `Rhea.trigger(event:param:)`, you can include
/// an additional parameter that will be passed to the callback via the `RheaContext`.
///
/// ```swift
/// #rhea(time: .load, priority: .veryLow, repeatable: true, func: { _ in
/// print("~~~~ load in Account Module")
/// })
///
/// #rhea(time: .registerRoute, func: { _ in
/// print("~~~~ registerRoute in Account Module")
/// })
///
/// // Use a StaticString as event directly
/// #rhea(time: "ACustomEventString", func: { _ in
/// print("~~~~ custom event")
/// })
///
/// // Example of using async execution
/// #rhea(time: .load, async: true, func: { _ in
/// // This will run on a background thread
/// performHeavyTask()
/// })
///
/// // Example of manually dispatching to background queue when async is false
/// #rhea(time: .load, func: { _ in
/// DispatchQueue.global().async {
/// // Perform background task
/// }
/// })
/// ```
/// - Note: ⚠️⚠️⚠️ When extending ``RheaEvent`` with static constants, ensure that
/// the constant name exactly matches the string literal value. This practice
/// maintains consistency and prevents confusion.
///
@freestanding(declaration)
public macro rhea(
time: RheaEvent,
priority: RheaPriority = .normal,
repeatable: Bool = false,
async: Bool = false,
func: RheaFunction
) = #externalMacro(module: "RheaTimeMacros", type: "WriteTimeToSectionMacro")
添加 CodeSnippets 到 XCode 以提高效率。
~/Library/Developer/Xcode/UserData/CodeSnippets/
由于业务需要自定义事件，例如这样
extension RheaEvent {
public static let homePageDidAppear: RheaEvent = "homePageDidAppear"
public static let registerRoute: RheaEvent = "registerRoute"
public static let didEnterBackground: RheaEvent = "didEnterBackground"
}
推荐的方法是将此框架包装在另一层中，例如命名为 RheaExtension
BusinessA BusinessB
↓ ↓
RheaExtension
↓
RheaTime
此外，RheaExtension 不仅可以自定义事件名称，还可以封装定时事件的业务逻辑
#rhea(time: .appDidFinishLaunching, func: { _ in
NotificationCenter.default.addObserver(
forName: UIApplication.didEnterBackgroundNotification,
object: nil,
queue: .main
) { _ in
Rhea.trigger(event: .didEnterBackground)
}
})
外部使用
#rhea(time: .didEnterBackground, repeatable: true, func: { _ in
print("~~~~ app did enter background")
})
在依赖的 Package 中通过 swiftSettings:[.enableExperimentalFeature("SymbolLinkageMarkers")] 启用实验性功能
// Package.swift
let package = Package(
name: "RheaExtension",
platforms: [.iOS(.v13)],
products: [
.library(name: "RheaExtension", targets: ["RheaExtension"]),
],
dependencies: [
.package(url: "https://github.com/reers/Rhea.git", from: "1.2.2")
],
targets: [
.target(
name: "RheaExtension",
dependencies: [
.product(name: "RheaTime", package: "Rhea")
],
// Add experimental feature enable here
swiftSettings:[.enableExperimentalFeature("SymbolLinkageMarkers")]
),
]
)
// RheaExtension.swift
// After @_exported, other business modules and main target only need to import RheaExtension
@_exported import RheaTime
extension RheaEvent {
public static let homePageDidAppear: RheaEvent = "homePageDidAppear"
public static let registerRoute: RheaEvent = "registerRoute"
public static let didEnterBackground: RheaEvent = "didEnterBackground"
}
// Business Module Account
// Package.swift
let package = Package(
name: "Account",
platforms: [.iOS(.v13)],
products: [
.library(
name: "Account",
targets: ["Account"]),
],
dependencies: [
.package(name: "RheaExtension", path: "../RheaExtension")
],
targets: [
.target(
name: "Account",
dependencies: [
.product(name: "RheaExtension", package: "RheaExtension")
],
// Add experimental feature enable here
swiftSettings:[.enableExperimentalFeature("SymbolLinkageMarkers")]
),
]
)
// Business Module Account usage
import RheaExtension
#rhea(time: .homePageDidAppear, func: { context in
print("~~~~ homepageDidAppear in main")
})
在主 App Target 中，在 Build Settings 中启用实验性功能: -enable-experimental-feature SymbolLinkageMarkers 
// Main target usage
import RheaExtension
#rhea(time: .premain, func: { _ in
Rhea.trigger(event: .registerRoute)
})
此外，您可以直接传递 StaticString 作为时间键。
#rhea(time: "ACustomEventString", func: { _ in
print("~~~~ custom event")
})
添加到 Podfile
pod 'RheaTime'
由于 CocoaPods 不支持直接使用 Swift Macro，您可以将宏实现编译成二进制文件以供使用。集成方法如下，需要 s.pod_target_xcconfig 加载宏实现的二进制插件
// RheaExtension podspec
Pod::Spec.new do |s|
s.name = 'RheaExtension'
s.version = '0.1.0'
s.summary = 'A short description of RheaExtension.'
s.description = <<-DESC
TODO: Add long description of the pod here.
DESC
s.homepage = 'https://github.com/bjwoodman/RheaExtension'
s.license = { :type => 'MIT', :file => 'LICENSE' }
s.author = { 'bjwoodman' => 'x.rhythm@qq.com' }
s.source = { :git => 'https://github.com/bjwoodman/RheaExtension.git', :tag => s.version.to_s }
s.ios.deployment_target = '13.0'
s.source_files = 'RheaExtension/Classes/**/*'
s.dependency 'RheaTime', '1.2.2'
# Copy following config to your pod
s.pod_target_xcconfig = {
'OTHER_SWIFT_FLAGS' => '-enable-experimental-feature SymbolLinkageMarkers -Xfrontend -load-plugin-executable -Xfrontend ${PODS_ROOT}/RheaTime/Sources/Resources/RheaTimeMacros#RheaTimeMacros'
}
end
Pod::Spec.new do |s|
s.name = 'Account'
s.version = '0.1.0'
s.summary = 'A short description of Account.'
s.description = <<-DESC
TODO: Add long description of the pod here.
DESC
s.homepage = 'https://github.com/bjwoodman/Account'
s.license = { :type => 'MIT', :file => 'LICENSE' }
s.author = { 'bjwoodman' => 'x.rhythm@qq.com' }
s.source = { :git => 'https://github.com/bjwoodman/Account.git', :tag => s.version.to_s }
s.ios.deployment_target = '13.0'
s.source_files = 'Account/Classes/**/*'
s.dependency 'RheaExtension'
# Copy following config to your pod
s.pod_target_xcconfig = {
'OTHER_SWIFT_FLAGS' => '-enable-experimental-feature SymbolLinkageMarkers -Xfrontend -load-plugin-executable -Xfrontend ${PODS_ROOT}/RheaTime/Sources/Resources/RheaTimeMacros#RheaTimeMacros'
}
end
或者，如果不使用 s.pod_target_xcconfig 和 s.user_target_xcconfig，您可以在 podfile 中添加以下脚本进行统一处理
post_install do |installer|
installer.pods_project.targets.each do |target|
rhea_dependency = target.dependencies.find { |d| ['RheaTime', 'RheaExtension'].include?(d.name) }
if rhea_dependency
puts "Adding Rhea Swift flags to target: #{target.name}"
target.build_configurations.each do |config|
swift_flags = config.build_settings['OTHER_SWIFT_FLAGS'] ||= ['$(inherited)']
plugin_flag = '-Xfrontend -load-plugin-executable -Xfrontend ${PODS_ROOT}/RheaTime/Sources/Resources/RheaTimeMacros#RheaTimeMacros'
unless swift_flags.join(' ').include?(plugin_flag)
swift_flags.concat(plugin_flag.split)
end
# Add SymbolLinkageMarkers experimental feature flag
symbol_linkage_flag = '-enable-experimental-feature SymbolLinkageMarkers'
unless swift_flags.join(' ').include?(symbol_linkage_flag)
swift_flags.concat(symbol_linkage_flag.split)
end
config.build_settings['OTHER_SWIFT_FLAGS'] = swift_flags
end
end
end
end
代码用法与 SPM 相同。
Asura19, x.rhythm@qq.com
Rhea 基于 MIT 许可证发布。有关更多信息，请参见 LICENSE 文件。