From 7f206376de8716d11d8d7f9bedce3dfff1b141ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Desbiens?= Date: Tue, 23 Jun 2026 19:37:56 -0400 Subject: [PATCH] Strengthened txm_module_object_deallocate deprecation notice Rewrote the API description to lead with a prominent WARNING admonition and a clear 'Do not use' directive. Added an explanation of why the function is deprecated (the dispatch layer already handles pool release) and a concrete example showing the correct pattern (tx_timer_delete only, no separate deallocation call). Removed the misleading example that showed txm_module_object_deallocate being called. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../modules/ROOT/pages/chapter4.adoc | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/rtos-docs/threadx-modules/modules/ROOT/pages/chapter4.adoc b/rtos-docs/threadx-modules/modules/ROOT/pages/chapter4.adoc index e7963d2..d93d9c6 100644 --- a/rtos-docs/threadx-modules/modules/ROOT/pages/chapter4.adoc +++ b/rtos-docs/threadx-modules/modules/ROOT/pages/chapter4.adoc @@ -141,18 +141,37 @@ status = txm_module_object_allocate(&queue_pointer, sizeof(TX_QUEUE)); Deallocate previously allocated object memory -=== Prototype +WARNING: *_This service is deprecated. Do not use it in new code, and remove any existing calls from your modules._* + +=== Reason for deprecation + +When a module calls a standard kernel delete service such as *_tx_timer_delete_*, *_tx_semaphore_delete_*, *_tx_queue_delete_*, or any other *_tx_*_delete_* service, the Module Manager dispatch layer automatically releases the associated object pool memory after the kernel cleanup completes. No separate deallocation call is required. + +Calling *_txm_module_object_deallocate_* on a live kernel object — one whose *_tx_*_delete_* service has not yet been called — frees the backing pool memory while the kernel still holds a reference to it. This is a use-after-free defect. + +=== What to do instead + +Remove any call to *_txm_module_object_deallocate_* from your module. Calling the appropriate *_tx_*_delete_* service is sufficient; pool memory deallocation is handled automatically by the Module Manager dispatch layer. [,c] ---- -UINT txm_module_object_deallocate(VOID *object_ptr); ----- +TX_TIMER my_timer; -=== Description +/* Allocate and create the timer. */ +txm_module_object_allocate(&my_timer, sizeof(TX_TIMER)); +tx_timer_create(&my_timer, "my timer", my_callback, 0, 10, 10, TX_AUTO_ACTIVATE); + +/* When done: delete the timer. The dispatch layer releases pool memory + automatically. Do NOT call txm_module_object_deallocate. */ +tx_timer_delete(&my_timer); +---- -*_This service has been deprecated because it is no longer needed_*. +=== Prototype -The memory that was previously allocated via *_txm_module_object_allocate_* is deallocated in the *_tx_*_delete_* service. +[,c] +---- +UINT txm_module_object_deallocate(VOID *object_ptr); +---- === Input parameters @@ -160,25 +179,12 @@ The memory that was previously allocated via *_txm_module_object_allocate_* is d === Return values -* *TX_SUCCESS* (0x00) Successful object allocate. +* *TX_SUCCESS* (0x00) Successful object deallocation. === Allowed from Module threads -=== Example - -[,c] ----- -TX_QUEUE *queue_pointer; - -/* Deallocate control block for a module message queue. */ -status = txm_module_object_deallocate(queue_pointer); - -/* If status is TX_SUCCESS the object memory associated - with queue_pointer is deallocated. */ ----- - === See also * <>