All posts by Ken Bourassa

Interface better practices

Today’s post is inspired from a question I answered on stackoverflow a while ago.  I’m bringing you some important point to consider when using interface.

First, one thing worth mentioning is that interface are not necessarily reference counted.  For example, TComponent implements IInterface, but if we look at it’s AddRef and Release methods, they both returns -1 indicating no reference counting occurs. TInterfacedObject, on the other hand, does take care of the reference counting. This is an important distinction because it affects how we should use interface.

Reference-counted interface

When using those, it’s usually preferable to avoid keeping a reference to the implementing object as we have no control on the lifetime of the object, the object will get destroyed at the same time it’s last interface reference is cleared.

If we absolutely need to keep the object reference around, we have 2 options.

  1. Keep an interface variable alongside the object variable to keep the object alive.

    [Delphi]
    TMyClass = class(TInterfaceObject);
    […]
    TForm1 = class(TForm)
    FObject : TMyClass;
    FObjectIntf : IUnknown;
    public
    […]
    //Creating the object
    FObject := TMyClass.Create;
    FObjectIntf := FObject;
    //Destroying the object
    FObject := nil; //Do NOT free the object
    FObjectIntf := nil; //FObject’s Destructor is called here.
    [/delphi]

  2. Use a FreeNotification mechanism to set the object’s variable back to nil when it is freed. This is built-in TComponent. Even though our class isn’t derived from TComponent, we can still leverage the functionality like this :

    [Delphi]
    TMyClass = class(TInterfaceObject)
    FNotifier : TComponent
    […]
    TForm1 = class(TForm)
    private
    FObject : TMyClass;
    protected
    procedure Notification(AComponent: TComponent; Operation: TOperation);override;

    […]
    procedure TForm1.Notification(AComponent: TComponent; Operation: TOperation);
    begin
    inherited;
    if FObject.FNotifier = FComponent then
    FObject := nil;
    end;
    //Creating the object
    FObject := TMyClass.Create;
    Form1.FreeNotification(FObject.FNotifier);
    //Destroying the object
    FObject.Free; //Here, FObject is assigned.
    Assert(FObject = nil); //Here, FObject is not assigned anymore, it was set to “nil” in TForm1.Notification.
    [/delphi]

When working with reference counted interface, it is worth nothing that, if 2 interfaces reference each others, they are never going to be freed. This is called “Circular Reference”. This is also seen with Automatic Reference Counting (ARC). The best method to break circular reference is a subject I still have to research (Especially in regard to the new [weak]  keyword) so I won’t make any suggestion here, but I thought it was worth mentioning.

Non reference-counted interface

Here, we need to keep an object reference around to be able to free our object’s memory as it won’t be freed through reference counting and, unless it implements IDisposable or a similar interface, we can’t free it from the interface reference.  Thus, we have the opposite problem.  We are unable to determine if there are references to our object left.

That being said, the problem isn’t specific to interface. The same problem would occur if we would pass the reference to our object around as a simple object.  Since this post is more about interfaces, I won’t delve into it here (though I might write about it some other time). But, one of the ways to make sure no references are left to our object is (*drum roll*), FreeNotification.

In which circumstance would we want to use interface without the reference counting?  Interfaces are tools and a tool’s usefulness is mostly limited by one’s imagination. But one I can name on the top of my head is using it as a “method binding” technique or pseudo “Duck Typing“. One such example can be seen in one of my previous post here.  Interface is also pretty much how anonymous methods are implemented “behind the scene”. I’m sure you guys can figure out clever usage for them!

One manager to rule them all

I guess I feel I’m not challenged enough at my job because sometime I deliver way more than I was asked (which got me in trouble once or twice).

I was once asked to develop a simple cache manager. We were downloading documents from a server, and we wanted to have a local cache so we would only download them at most once a day.

The specifications were something like this :

  TOurDocumentCacheManager = class
  public
[...]
    procedure WriteToCache(const DocumentId : string; Document : TOurSpecificDocumentClassInstance);
    function ReadFromCache(const DocumentId : string; Document : TOurSpecificDocumentClassInstance) : Boolean; 
[...] 
  end; 

I felt this was WAY too specific for a job that is pretty general.  So I altered the specifications like this :

  ICacheable = interface(IStreamPersist)
    function GetUniqueId : String;
  end;

  TCacheManager = class
  public
[...]
    procedure WriteToCache(Document : ICacheable);
    function ReadFromCache(Document : ICacheable) : Boolean; 
[...] 
  end; 

So, instead of having a cache manager that can manage a single type of document, we have a cache manager that can manage them all.

Believe it or not, that still landed me a few complaints, though all easily refuted. One of which might even come to your mind…  “What if we want to cache an object from a 3rd party? We can’t magically add ICacheable to the object!”.  And this is a valid point, until we realize writing a ICacheable wrapper around an object is simpler than writing a new cache manager.

So… I guess the point I was trying to make here is how easy it is to limit the potential of the code we write. Sometime, it doesn’t involve much (if any) extra work to make our code more reusable, and it’s pretty much always worth it.

Shlemiel the painter strikes again

Once upon a time, I was introduced to Shlemiel.  Who is Shlemiel? For those too lazy to look up the link, he’s the guy from this joke :

Shlemiel gets a job as a street painter, painting the dotted lines down the middle of the road. On the first day he takes a can of paint out to the road and finishes 300 yards of the road. “That’s pretty good!” says his boss, “you’re a fast worker!” and pays him a kopeck.
The next day Shlemiel only gets 150 yards done. “Well, that’s not nearly as good as yesterday, but you’re still a fast worker. 150 yards is respectable,” and pays him a kopeck.
The next day Shlemiel paints 30 yards of the road. “Only 30!” shouts his boss. “That’s unacceptable! On the first day you did ten times that much work! What’s going on?”
“I can’t help it,” says Shlemiel. “Every day I get farther and farther away from the paint can!”

We can all agree Shlemiel wasn’t working very efficiently! Spotting inefficiency in tasks in the physical world is pretty easy because it’s very concrete. Doing the same in the programming world is a lot harder since we don’t usually observe the execution of our code, we usually only observe the end result. It’s very easy to copy Shlemiel’s without even realizing it.

Us, Delphi programmers, we can find example of Shelmiel’s work pretty close to home. There’s a few of those in Delphi’s VCL/RTL. The one I’m going to introduce today is StringReplace.

StringReplace is notoriously slow for large string, and after profiling the function to figure out why it is so slow, I’m pretty amazed Embarcadero didn’t bother to fix its implementation as it is very simple to fix.

The source of the problem lies here :

[Delphi]

Offset := AnsiPos(Patt, SearchStr);
if Offset = 0 then
begin
Result := Result + NewStr;
Break;
end;
Result := Result + Copy(NewStr, 1, Offset – 1) + NewPattern;
NewStr := Copy(NewStr, Offset + Length(OldPattern), MaxInt); //This line is a problem
if not (rfReplaceAll in Flags) then
begin
Result := Result + NewStr;
Break;
end;
SearchStr := Copy(SearchStr, Offset + Length(Patt), MaxInt); //This line is a problem
[/Delphi]

The 2 flagged line take together more than 90% of execution time when called with a large string as input. Now, what happens here is this :

Shlemiel realized how inefficient his methods were. So the next day, shlemiel decided to transport to the whole road to his paint can. That way, he would need to walk a lot less to paint the road!

Everytime the pattern is matched, they make a whole copy of NewStr and a whole copy of SearchStr. This makes the algorithm run in O(n2) time. Fixing this is relatively simple:  Instead of taking the road to the paint can, take the paint can to the road! … or in other word, scanning the string in place.

It is a relatively simple change to make, yet, it takes the function from O(n2) to O(n). A simple test, loading Winapi.Windows.pas as input and replacing “A” with “B” would take  about 2 minutes to run with the original code, but less than 10 msec when scanning in-place.

If you are curious about the new implementation for StringReplace, I made my implementation available in a unit that automatically replace the implementation from System.StrUtils. You will need :

  • ab.Patch.System.SysUtils.pas
  • ab.MemUtils.pas

If there’s another function that’s you guys would like me to take a look at, let me know in the comments.

Evolving from the primitive world

One of the novelty of the recent versions of Delphi is the built-in record helper for the primitive types (string, Integer, etc.). Record helper are essentially class helper for record (and apparently primitive types). The new class helper allows code syntax like

[Code language=”delphi”]
ShowMessage(1.ToString);
[/code]

to compile and work the same as the good old

[Code language=”delphi”]
ShowMessage(IntToStr(1));
[/code]

One of the drawback of record helper is, like class helper, there can only be 1 “active” at any given point in the source code. Any new helper we declare will hide or be hidden by (depending on scope resolution) Delphi’s helper. Also, record helpers are pretty good for generic operations on primitives, but what about more specific operations? It is not ideal to have something like this compile:

[Code language=”delphi”]
var
sFirstName : string;
begin
[…]
sFirstName.GetAreaCode;
[/code]

This problem is especially true for string, as we quite often use strings formatted in specific ways to give them special meanings.

My favorite approach when I have to work with such string is to create what I like to call “Smart Primitive”.

What I like about this concept is that, for one, the validity of the format is done at the moment of initialization. That means that any routine that use the record can assume the value is in an accepted format. [1]

So, what is a smart primitive?

  1. Smart primitives are opaque records. Only their methods should use their internal fields. Very often, they will only have a single internal field.
  2. They implement at least 1 implicit conversion to and from a primitive type. That is how the internal field of the record should be initialized.

Now, lets get a little more concrete.  Earlier, I gave the GetAreaCode example, so lets see how a PhoneNumber basic smart primitive would look like.

In North America, phone numbers always have 10 digits, the area code being the first 3 [2]. Now, lets say we want to allow users to enter any of those formats :

  1. (999)999-9999
  2. 999-999-9999
  3. (999)-999-9999
  4. 9999999999

Here’s a basic implementation :

[Code language=”delphi”]
TabPhoneNum = record
private
FPhoneNum : INT64;
FOriginalValue : string;
public
class operator Implicit(S : String) : TabPhoneNum;
class operator Implicit(APhoneNum : TabPhoneNum) : String;
[…]
function GetAreaCode : Integer;
end;

class operator TabPhoneNum.Implicit(S: String): TabPhoneNum;
var sNormalized : String;
begin
sNormalized := NormalizePhoneNum(S); //Remove “(“,”)”,”-” and ” ”
FPhoneNum := StrToInt64(sNormalized ); //If the normalized string is not a valid integer, we want to raise
if GetDigitsCount(FPhoneNum) <> 10 then
Raise Exception.Create(S + ‘ is not a valid phone number’);
FOriginalValue := S;
end;

function TabPhoneNum.GetAreaCode : Integer;
begin
//We don’t need to validate the format of FOriginalValue, it’s been done already
//We don’t need to validate the number of digits, it’s been done already
Result := (FPhoneNum div 10000000); // we don’t need to “mod 100” because we validated it is 10 digits
end;

function TForm1.GetAreaCode(const APhoneNum : TabPhoneNum) : Integer;
begin
Result := APhoneNum.GetAreaCode;
end;

procedure TForm1.Button1Click(Sender : TObject);
begin
ShowMessage(GetAreaCode(Edit1.Text).ToString);
//here, if Edit1.Text is not in a valid format, it will raise an exception before calling Tform1.GetAreaCode.
end;
[/code]

In the implementation of GetAreaCode, we see one of the main advantage of smart primitives. We don’t have to deal with all the different string format and we don’t have to validate the number of digits in FPhoneNum because it was already done when the record was first initialized.

Of course, we could simply implement GetAreaCode like this :

[Delphi]
function GetAreaCode(const S : string) : Integer;
begin
Result := Copy(S, 2, 3).ToInteger;
end;
[/Delphi]

and go based on the design by contract philosophy, and state that the input string needs to start with “(” followed immediately by the area code, etc. But that puts the burden of the contract on the caller. For a single method, it might make sense, but if you have a collection of methods having the exact same preconditions in the contract, it would make more sense laying out the contract’s preconditions as being the smart primitive’s contract instead, and then let its methods work with an already enforced contract.

This also has the advantage of “scoping” the methods where they belong. One too many time I have opened a unit filled with routine taking a single string as a parameter, none of them accepting the same “kind” of string.

So, how do you like this? Already doing it? Like it? Hate it?  Let me know what you think!

1.I say “Accepted” and not “Valid” on purpose. A smart primitive can allow invalid values.
2.Except in Mexico where it varies. For the sake of simplicity, I’ve excluded this fact.

Allowing breaking changes to break is good

I remember a discussion with a coworker some time ago… He came and proudly told me he always used “.AsString”, “.AsInteger”, etc when dealing with TField’s descendant instead of using “.Value”. His rational was that, if the field type changes, using Value would would not compile while using AsString would.

Take the following code :

  
  FField.AsString := 'Hello World';
  FField.Value    := 'Hello World';

If FField is a TWideString field, both line means essentially the same. On the other hand, If FField is a TIntegerField, the 2nd line won’t compile.

While I need to admit my coworker was right, his approach was certainly better than mine at making sure a given line of code will keep compiling in the future, he was also wrong in believing this was a good thing.

In this particular example, even though FField.AsString would keep compiling if FField become a TIntegerField, it would just raise an exception at runtime trying to convert ‘Hello World’ to an Integer.

Personally, I tend to favor coding approach that will allow the compiler to catch problems at compile time. It’s one of the perks of working with a strongly typed language.

So, what do *I* do? I always use Field.Value for typed TField. When I’m working with untyped TField variable, then I never use Field.Value.

  
  var
    FTypedField   : TWideStringField;
    FUntypedField : TField;
    sSomeVariable : String;
[...]
  FTypedField.Value       := sSomeVariable ; 
  FUntypedField.AsString  := sSomeVariable ;

In this situation, if FTypedField becomes a TIntegerField, the code won’t compile. But why use AsString with an TField?  In this case, the advantage lies on the right side of the operation : If sSomeVariable’s type is changed, that won’t compile anymore.