It’s great to see news this week of one outcome of Symbian’s commitment to keep on improving developer experience. As announced on the Symbian Developer Network:
>>>>>>>
The new EUserHL Core Idioms library delivers:
- LString, a string class that handles its own buffer management and cleanup
- LCleanedupX and LManagedX, a set of cleanup management helper templates
- CONSTRUCTORS_MAY_LEAVE, a helper macro that enables single-phase construction
- OR_LEAVE, a helper macro to cleanly convert error-returning code into leaving code.
The necessary header files for exploiting the new code idioms library are supplied in a header EUserHL.h, supported by a DLL, EUserHL.DLL, and an EUserHL.SIS installable package, available for all Symbian OS v9-based devices.
This makes Symbian OS easier for programmers by:
- Making it simpler and cleaner to write correct cleanup-safe code, with fewer lines of code than before;
- Making an elegant, leave-safe implementation of the widely-used C++ RAII (Resource Allocation Is Initialization) idiom available for Symbian OS programming;
- Making it simpler and cleaner to write code involving arbitrary-length strings without choosing magic numbers for their length, and variable-length strings without performing manual memory management.
Using the Core Idioms library has a pervasive impact on line-of-code count and on simplicity and cleanness. That’s great when you write the code, and awesome when you come to maintain it.
The Core Idioms library delivers these improvements by exploiting the mapping of Symbian OS User::Leave() onto C++ throw, introduced in Symbian OS v9 and by relieving the application programmer of much explicit responsibility for memory management for strings and cleanup.
Idioms define the style by which programmers use an OS, and therefore have a pervasive ease-of-use impact in normal Symbian programming by programmers working at all levels of the software stack.
Use of this library is recommended for all new code. Only if you know you can do better by managing your own memory with traditional descriptor APIs, cleanup stack idioms, and two-phase construction, should you continue to use the traditional Symbian OS features instead of Core Idioms…
In conclusion, the EUserHL Core Idioms library allows:
- Experienced Symbian C++ developers to write robust and compact string-handling code with semi-automated exception handling;
- New Symbian C++ developers to use Symbian OS exceptions, the cleanup stack and descriptors more easily, with fewer programming errors and more rapid application development.
For further information, and to obtain the new library, see the Downloads section of the Symbian Developer Network page.
(This is just the outcome of the first phase of the “Core Idioms” project: there’s lots more in the pipeline.)
13 Comments
Out of interest, is there any reason why this code wasn’t “born Open Source”? And are there any plans to release the source to the DLL soon? (Although I assume that it’ll eventually be integrated with a Symbian^N release).
Hi Tyson,
You’re right, ideally this code should have been released as Open Source.
We’ll find a way to get it released as Open Source as soon as possible!
// David W.
Interestingly, it looks like the sample code and header files are covered under the Symbian Foundation License 1.0 (which is the first piece of code I’ve seen under that license to date), and there’s a compiled version of the sample code itself, alongside the source-less DLL.
Thanks for following up, though.
Hrmm…I don’t know where the right place to post this is, but this seems as good as any…
There appears to be a bug within “emanaged.h”.
The function void ManagedPopCleanupStackItem(bool aIsManaged) is defined directly within the header, but is neither marked inline nor static.
The problem occurs when there are several source files that include this header file (even with the header guard). Each resultant object file will export the ManagedPopCleanupStackItem symbol and cause linker errors for multiply defined symbols.
Three possible solutions…
a. Declare the function inline:
Symbol won’t be created as the code is inline. Increase the size of each class that calls it. (The five LCleanupXXX classes).
b. Declare the function static:
Symbol won’t be exported outside the object file. Increase the size of each object file that includes the header file.
c. Leave the function prototype (declare it extern) and move the function definition:
Symbol only defined once, not as readily patched by end users.
Hi Alex,
Thanks for bug report. Software engineers from the Symbian Base Services team are looking at it now.
>I don’t know where the right place to post this is…
The best place will be the Symbian Foundation Bugzilla tracker, which will shortly become available via one of the symbian.org sites
// David W.
Interesting improvements.
Keep adding stuff to the framework, to make developer’s life easier.
I particularly like LString.
Another area of improvement could be, for example, creation of a new Client-Server architecture sub-classes that implement “sub-sessioning” automatically. Sometimes the Client-Server architecture efficiency is precluded to “young developers” because of the “trickiness”.
Anyway, again, keep bringing this kind of stuff to the table.
Hi detronizator,
>Another area of improvement could be, for example, creation of a new Client-Server architecture sub-classes that implement “sub-sessioning” automatically
It looks like you’ve been reading the specs for the Core Idioms 2 project!
Or maybe this is a case of “great minds think alike”.
// David W.
Not to leave another problem here, but the docs make reference to a method “EnsureCapacity” on the LString[8|16] classes that is not defined.
// Alex Garbutt
@DavidW: That sounds great!
No, I didn’t read anything about it… is it public or going to be?
Hi Alex,
>the docs make reference to a method “EnsureCapacity” on the LString[8|16] classes that is not defined
Hmm, it looks like the documentation did not keep up with some changes in the design of the APIs.
Most users of LString will be happy to accept the automated buffer allocation and re-allocation that takes place behind the scenes of this class. The EnsureCapacityL function was one approach to allow users to override this behaviour. In the final design, however, the function ReserveFreeCapacityL takes over this use case (though with slightly different semantics).
Here’s the description of ReserveFreeCapacityL:
/**
Ensures that the remaining unused space is more than the supplied value.
May reallocate a larger storage space to meet the requirement.
As a result MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.
Typically, you use this method to reserve a known amount of required space in one go instead of relying on the automatic growth pattern.
@param aExtraSpaceLength The extra space required.
@leave KErrNoMemory if the the buffer needs to be reallocated and there are insufficient resources to do so.
@panic USER 11 if aLength is negative
*/
// David W.
That’s what I figured. Thanks!
Hey,
why when I installing EUserHL.sis on my N95 i get warning message “application not compatible with the phone”? I can user EUserHL if end users will also see that message.
There is a new release available now at:
https://developer.symbian.com/main/documentation/symbian_cpp/symbian_cpp/LCL.jsp
that deals with the duplicate symbols issue and documentation updates.
Another minor release with improvements can be expected soon.
-Subhasis