Skip to content

Commit c87cd1c

Browse files
I've updated the Jules.md file with information about Analytics initialization and Future management.
This update incorporates further feedback from you into Jules.md: 1. **Clarified Analytics Initialization:** The "API Surface" -> "Initialization" section now specifies that Firebase Analytics uses a different initialization pattern (`firebase::analytics::Initialize(app)`) compared to the common `GetInstance(app, ...)` pattern of other services. It also notes that Analytics functions are typically called globally. 2. **Added Future Lifecycle Management Guidance:** A new point in "Best Practices" -> "Resource Management" emphasizes the importance of ensuring `Future` objects complete their course (e.g., via `OnCompletion` or by checking results) to prevent potential issues with operations not finalizing or resources not being cleaned up promptly. These changes provide more nuanced guidance for interacting with the Firebase C++ SDK.
1 parent 2263a34 commit c87cd1c

File tree

1 file changed

+30
-5
lines changed

1 file changed

+30
-5
lines changed

Jules.md

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -174,14 +174,26 @@ Database).
174174
* `firebase::AppOptions` can be used to configure the app with specific
175175
parameters if not relying on a `google-services.json` or
176176
`GoogleService-Info.plist` file.
177-
2. **Service Instances**: Once `firebase::App` is initialized, you obtain
178-
instances of specific Firebase services.
179-
* Examples:
177+
2. **Service Instances**: Once `firebase::App` is initialized, you generally
178+
obtain instances of specific Firebase services using a static `GetInstance()`
179+
method on the service's class, passing the `firebase::App` object.
180+
* Examples for services like Auth, Database, Storage, Firestore:
180181
* `firebase::auth::Auth* auth = firebase::auth::Auth::GetAuth(app, &init_result);`
181182
* `firebase::database::Database* database = firebase::database::Database::GetInstance(app, &init_result);`
183+
* `firebase::storage::Storage* storage = firebase::storage::Storage::GetInstance(app, &init_result);`
182184
* Always check the `init_result` (an `InitResult` enum, often
183-
`firebase::kInitResultSuccess` on success) to ensure the service was
184-
initialized successfully.
185+
`firebase::kInitResultSuccess` on success) to ensure these services
186+
were initialized successfully.
187+
* **Note on Analytics**: Some products, like Firebase Analytics, have a
188+
different pattern. Analytics is typically initialized with
189+
`firebase::analytics::Initialize(const firebase::App& app)` (often
190+
handled automatically for the default `App` instance). After this,
191+
Analytics functions (e.g., `firebase::analytics::LogEvent(...)`) are
192+
called as global functions within the `firebase::analytics` namespace,
193+
rather than on an instance object obtained via `GetInstance()`.
194+
Refer to the specific product's header file for its exact
195+
initialization mechanism if it deviates from the common `GetInstance(app, ...)`
196+
pattern.
185197

186198
### Asynchronous Operations: `firebase::Future<T>`
187199

@@ -337,6 +349,19 @@ API documentation.
337349
* **Pointers**: Standard C++ smart pointers (`std::unique_ptr`,
338350
`std::shared_ptr`) should be used where appropriate for managing
339351
dynamically allocated memory.
352+
* **`Future` Lifecycle**: Ensure `Future` objects returned from API calls are
353+
properly managed. While `Future`s handle their own internal memory for the
354+
result, the asynchronous operations they represent need to complete to
355+
reliably free all associated operational resources or to ensure actions
356+
(like writes to a database) are definitely finalized. Abandoning a `Future`
357+
(letting it go out of scope without checking its result, attaching an
358+
`OnCompletion` callback, or explicitly `Wait()`ing for it) can sometimes
359+
lead to operations not completing as expected or resources not being
360+
cleaned up promptly by the underlying services, especially if the `Future`
361+
is the only handle to that operation. Prefer using `OnCompletion` or
362+
otherwise ensuring the `Future` completes its course, particularly for
363+
operations with side effects or those that allocate significant backend
364+
resources.
340365

341366
## Immutability
342367

0 commit comments

Comments
 (0)