Skip to content

Commit 5fbb06d

Browse files
committed
Bluetooth: Host: Amend recycled() callback documentation
The API documentation for the recycled() callback predates [1], and still warns users to "treat this callback as an ISR", although it now runs on the system work-queue thread, as does disconnected(). "Making Bluetooth API calls" to "re-start connectable advertising or scanning" should no longer be "strongly discouraged". On the contrary, we can emphasize that this is the right event to listen for to initiate operations that will try to re-allocate a freed connection object. Mention that BT_MAX_CONN configures the size of the connection pool. Refs: - [1] efb5d83: Bluetooth: Host: Defer `conn.recycled()` to the syswq Signed-off-by: Christophe Dufaza <[email protected]>
1 parent b172093 commit 5fbb06d

File tree

1 file changed

+9
-5
lines changed
  • include/zephyr/bluetooth

1 file changed

+9
-5
lines changed

include/zephyr/bluetooth/conn.h

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1849,12 +1849,16 @@ struct bt_conn_cb {
18491849
* This callback notifies the application that it might be able to
18501850
* allocate a connection object. No guarantee, first come, first serve.
18511851
*
1852-
* Use this to e.g. re-start connectable advertising or scanning.
1852+
* The maximum number of simultaneous connections is configured
1853+
* by @kconfig{CONFIG_BT_MAX_CONN}, which usually defaults to a single connection.
18531854
*
1854-
* Treat this callback as an ISR, as it originates from
1855-
* @ref bt_conn_unref which is used by the BT stack. Making
1856-
* Bluetooth API calls in this context is error-prone and strongly
1857-
* discouraged.
1855+
* This is the event to listen for to start a new connection, connectable advertiser
1856+
* or scanner, both when the intention is to start it after the system is completely
1857+
* finished with an earlier connection, and when the application wants to start
1858+
* a connection for any reason but failed and is waiting for the right time to retry.
1859+
*
1860+
* This callback runs on the system workqueue thread,
1861+
* the usual precautions apply.
18581862
*/
18591863
void (*recycled)(void);
18601864

0 commit comments

Comments
 (0)