FreeCalypso > hg > gsm-codec-lib
changeset 544:bd32bb1e8dab
doc/EFR-library-API: document malloc-alternative provision
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 03 Oct 2024 08:22:41 +0000 |
parents | 53d3f48af107 |
children | b07dba7b8a4f |
files | doc/EFR-library-API |
diffstat | 1 files changed, 28 insertions(+), 5 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/EFR-library-API Sun Sep 29 02:41:28 2024 +0000 +++ b/doc/EFR-library-API Thu Oct 03 08:22:41 2024 +0000 @@ -22,11 +22,12 @@ struct EFR_encoder_state and struct EFR_decoder_state are opaque structures to library users: you only get pointers which you remember and pass around, but <gsm_efr.h> does not give you full definitions of these structs. As a library -user, you don't even get to know the size of these structs, hence the necessary -malloc() operation happens inside EFR_encoder_create() and EFR_decoder_create(). -However, each structure is malloc'ed as a single chunk, hence when you are done -with it, simply call free() to relinquish each encoder or decoder state -instance. +user, you ordinarily don't even need to know the size of these structs, hence +the necessary malloc() operation happens inside EFR_encoder_create() and +EFR_decoder_create(). (But see a later section of this document regarding +alternative memory allocation schemes.) However, each structure is malloc'ed +as a single chunk, hence when you are done with it, simply call free() to +relinquish each encoder or decoder state instance. EFR_encoder_create() and EFR_decoder_create() functions can fail if the malloc() call inside fails, in which case the two libgsmefr functions in question return @@ -206,6 +207,28 @@ this flag passed to EFR_encoder_reset() always takes effect. There is no provision for changing this mode within an encoder session without a full reset. +These reset functions may be used to implement an alternative memory allocation +scheme, if there is a requirement or desire to use something other than plain +malloc(). To make such alternative schemes possible, the following const +"variables" are provided beginning with libgsmefr version 1.2.0: + +extern const unsigned EFR_encoder_state_size; +extern const unsigned EFR_decoder_state_size; + +Using this feature, one can replace EFR_encoder_create() and +EFR_decoder_create() with something like the following (example for +applications based on Osmocom libraries): + + struct EFR_encoder_state *enc_state; + enc_state = talloc_size(ctx, EFR_encoder_state_size); + if (enc_state) + EFR_encoder_reset(enc_state, dtx_flag); + + struct EFR_decoder_state *dec_state; + dec_state = talloc_size(ctx, EFR_decoder_state_size); + if (dec_state) + EFR_decoder_reset(dec_state); + Public const datum: decoder homing frame ========================================