Skip to content

Strengthened txm_module_object_deallocate deprecation notice #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fdesbiens wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Strengthened txm_module_object_deallocate deprecation notice #32

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 26 additions & 20 deletions rtos-docs/threadx-modules/modules/ROOT/pages/chapter4.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,44 +141,50 @@ 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

* *object_ptr* Object pointer to deallocate.

=== 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

* <<Threadx_Module_APIs,Threadx Module APIs>>
Expand Down