When working with files from Delphi you might want to display the size of a file to the user in a Explorer-like format where the file size is not displayed in bytes – but the display depends on the size of the actual file.

To most users “45678123 b” is confusing – where “43.56 MB” is much more user friendly.

Format Byte Size to String

A custom Delphi function, FormatByteSize, converts a byte value into a string that represents the number expressed as a size value in bytes, kilobytes, megabytes, or gigabytes, depending on the size.

    //Format file byte size
    function FormatByteSize(const bytes: Longint): string;
    const
      B = 1; //byte
      KB = 1024 * B; //kilobyte
      MB = 1024 * KB; //megabyte
      GB = 1024 * MB; //gigabyte
    begin
      if bytes > GB then
        result := FormatFloat('#.## GB', bytes / GB)
      else
        if bytes > MB then
          result := FormatFloat('#.## MB', bytes / MB)
        else
          if bytes > KB then
            result := FormatFloat('#.## KB', bytes / KB)
          else
            result := FormatFloat('#.## bytes', bytes) ;
    end;

Too Read The Previous Article Please Read This..
Abstract: Semaphores are used to coordinate multiple threads and processes. That semaphores provide multiple threads with simultaneous access to a shared resource is highlighted by the TFixedConnectionPool class described in this article.

Semaphores are like mutexes on steroids. Not only do they provide for blocking thread synchronization, but they permit two or more threads, up to some specified maximum number, to work concurrently with a shared resource. As a result, they are unlike most other synchronization objects, which typically provide access to one thread at a time. For an introduction to the creation and use of semaphores, read the preceding article in this series on the Borland Developer Network site by clicking here.

This unique feature of a semaphore, the ability to provide two or more threads with simultaneous access to a resource, lends itself very well to the implementation of objects that contain a fixed number of resources that need to be made available in a multithreaded environment. Two common examples of objects of this type are thread pools and database connection pools. This article discusses the use of a semaphore to implement a connection pool.

Connection Pool Overview

A connection pool is an object designed to provide thread-safe access to a limited number of database connections in a multithreaded environment. In most scenarios, a connection pool contains one or more active database connections that can be used by any thread needing to work with the database.

A connection pool provides two primary benefits. The first is related to performance. Making and dropping a connection to a database is a relatively time consuming process. Depending on the environment, if each thread must make and then drop a connection each time data access is needed, a significant amount of processing power will be spent on the connection process. By comparison, a connection pool includes a fixed number of connections that can be shared among many threads. When a thread needs to work with a database, it obtains a handle to an existing connection that it uses temporarily. This reuse can dramatically reduce the number of times a connection is made and dropped, thereby producing an overall increase in performance.

The second benefit is related to connection counts. Many database licensing schemes permit only a limited number of simultaneous connections to the database. A connection pool, therefore, becomes a convenient mechanism for ensuring that no more than some fixed maximum number of connections can be active at a given moment. While a semaphore can be used outside a connection pool to manage the maximum number of simultaneous connections, a connection pool automatically provides this feature with the addition benefit of increased performance.

The FixedConnectionPool

The fixed connection pool unit, available for download from Code Central (by clicking here), provides an implementation of a connection pool. The purpose of this code is to demonstrate the use of a semaphore to provide multithreaded access to a limited resource (the connections in the pool). If you want to use this code in a production application, it is your responsibility to certify that the connection pool meets your application’s requirements. Note also, as of this writing, this connection pool has not been tested on a multiprocessor system.

There are four type declarations used in this connection pool. One is an interface and three are classes. The interface, named IConnection, defines the formal declaration of the connection pool interface, and also provides for the lifecycle management of individual connections.

The three classes consist of the connection pool object itself, named TFixedConnectionPool, as well as two helper classes. These helper classes are TConnectionModule, a data module descendant that is created once for each open connection, and TCleanupThread, a TThread descendant that drops connections that have not been used after some specified period of time.
IConnection

Let’s begin by considering the IConnection interface. This interface declaration is shown here:

 IConnection = Interface(IInterface)
  //CHANGE
  //To use a connection of another type, change the
  //return type of the Connection function
  function Connection: TSQLConnection;
  function GetRefCount: Integer;
  function GetLastAccess: TDateTime;
  property LastAccess: TDateTime read GetLastAccess;
  property RefCount: Integer read GetRefCount;
end;

The Connection function returns a SQLConnection reference, which when implemented, refers to a SQLConnection object that is actively connected to a database. If you want to modify this connection pool to use a data access technology other than dbExpress, you need to change the return type of this Connection function to some other connection type, such as an TADOConnection (ADO), TIBDatabase (Interbase Express), or TSession (BDE).

The functions GetRefCount and GetLastAccess are the accessor methods for the RefCount and LastAccess properties, respectively. RefCount returns the number of current references to the IConnection implementing object. LastAccess returns the TDateTime of the last release of the IConnection implementing object. This value is used by the cleanup thread object to test whether the IConnection implementing object has gone unused for an extended period of time, and if so, to drop the unused connection.

TConnectionModule

The actual database connection is provided for by the TConnectionModule class. This class is a TDataModule descendant, and the connection component appears on this data module, as shown in the following figure.

TConnectionModule implements the IConnection interface. The SQLConnection that appears on this data module is the reference that is returned when the Connection method is invoked. As mentioned in the preceding discussion of the IConnection interface, if you want to use a connection other than dbExpress, you will replace this SQLConnection component with one that provides a connection using an alternative data access mechanism.

The following is the declaration of the TConnectionModule class. This class is commented extensively, and I am leaving these comments in this code segment for clarity.

//This data module provides the implementation
//of the IConnection interface. To use a data access
//mechanism other than dbExpress, modify the components
//that appear on this data module, and change the class
//of the Connection function in the IConnection interface
//as well as in this class.
TConnectionModule = class(TDataModule, IConnection)
  SQLConnection1: TSQLConnection;
private
  { Private declarations }
protected
  FRefCount: Integer;
  FLastAccess: TDateTime;
  //When the data module is created the
  //connection pool that creates the data module
  //will assign its critical section to this field.
  //The data module will use this critical section
  //to synchronize access to its reference count.
  CriticalSection: TCriticalSection;
  //This semaphore points to the FixedConnectionPool's
  //semaphore. It will be used to call ReleaseSemaphore
  //from the _Release method of the TDataModule.
  Semaphore: THandle;
  //These two static methods are reintroduced
  //in order to implement lifecycle management
  //for the interface of this object.
  //Normally, unlike normal COM objects, Delphi
  //TComponent descendants are not lifecycle managed
  //when used in interface references.
  function _AddRef: Integer; stdcall;
  function _Release: Integer; stdcall;
  {IConnection methods}
  function GetLastAccess: TDateTime;
  function GetRefCount: Integer;
public
  { Public declarations }
  {IConnection method}
  //CHANGE
  //To use a connection of another type, change the
  //return type of the Connection function
  function Connection: TSQLConnection;
end;

The Connection, GetLastAccess, and GetRefCount methods are implemented in this class to satisfy the implementation of the IConnection interface. The _AddRef and _Release static methods are reintroduced in this class to implement lifecycle management on the interface. This is necessary since the _AddRef and _Release methods introduced in TComponent (a TDataModule ancestor), do not implement lifecycle management through reference counting for VCL (visual component library) objects. This lifecycle management plays a critical role in the management of the connection pool.

The TConnectionModule class also contains two member fields, CriticalSection and Semaphore. Both of these members are used to point to a TCriticalSection and a semaphore (a THandle), both of which are maintained by the TFixedConnectionPool class (and are assigned to these members by the TFixedConnectionPool instance when it creates an instance of the connection module).

The critical section class is used to synchronize access to the internal reference count of the TConnectionPool instances, and the semaphore controls access to instances of the TConnectionModule class. This is shown in the _AddRef and _Release method implementations, shown here.

function TConnectionModule._AddRef: Integer;
begin
//increment the reference count
CriticalSection.Enter;
try
  Inc(FRefCount);
  Result := FRefCount;
finally
  CriticalSection.Leave;
end;
end;

function TConnectionModule._Release: Integer;
begin
//decrement the reference count
CriticalSection.Enter;
try
  Dec(FRefCount);
  Result := FRefCount;
  //if not more references, call Destroy
  if Result = 0 then
    Destroy
  else
    Self.FLastAccess := Now;
finally
  CriticalSection.Leave;
  if FRefCount = 1 then
    ReleaseSemaphore(Semaphore, 1, nil);
end;
end;

Notice that the critical section is locked before the internal reference count can be incremented or decremented. Also, notice that if the reference count of a TConnectionModule instance drops to one that ReleaseSemaphore is called. When the internal reference count on a TConnectionModule instance drops to one, the thread that was using the connection has released it, and the only remaining reference to the connection module is held by the connection pool itself.

TFixedConnectionPool

The connection pool is implemented by the TFixedConnectionPool class, shown in the following code segment. Once again, the extensive comments have been left in the code for clarity.

//This is the class that manages the connection pool
TFixedConnectionPool = class(TObject)
private
  FPool: array of IConnection;
  FPoolSize: Integer;
  FTimeout: LargeInt;
  CleanupThread: TCleanupThread;
  //This semaphore is used to limit the number of
  //simultaneous connections. When the nth+1 connection
  //is requested, it will be blocked until a connection
  //becomes available.
  Semaphore: THandle;
  //This is the critical section that synchronizes
  //access to the connection module reference counts
  CriticalSection: TCriticalSection;
public
  //This overloaded constructor takes two optional
  //parameters. These parameters specify the size
  //of the connection pool, as well as how long idle
  //connections in the connection pool will be kept.
  constructor Create(const PoolSize: Integer = 10;
    const CleanupDelayMinutes: Integer = 5;
    const Timeoutms: LargeInt = 10000); overload;
  destructor Destroy; override;
  //This function returns an object
  //that implements the IConnection interface.
  //This object can be a data module, as was
  //done in this example.
  function GetConnection: IConnection;
end;

One of the more notable elements of this declaration is the FPool member, which is a dynamic array of IConnection references. This array provides the list of pointers to the connections in the connection pool.

constructor TFixedConnectionPool.Create(const PoolSize: Integer = 10;
      const CleanupDelayMinutes: Integer = 5;
      const Timeoutms: LargeInt = 10000);
begin
  FPoolSize := PoolSize;
  FTimeout := Timeoutms;
  Semaphore := CreateSemaphore(nil, PoolSize, PoolSize, '');
  CriticalSection := TCriticalSection.Create;
  //Set the length of the connection pool
  SetLength(FPool, PoolSize);
    //Create and start the cleanup thread
  CleanupThread := TCleanupThread.Create(True,
    CleanupDelayMinutes);
  with CleanupThread do
  begin
    FreeOnTerminate := True;
    Priority := tpLower;
    FixedConnectionPool := Self;
    Resume;
  end;
end;

As you can see from this code, the constructor stores the cleanup delay and timeout values in member fields of the connection pool object. It then creates the semaphore, setting the number of available locks and the maximum number of locks to the size of the pool. As a result, initially the connection pool is created with all connections available. Also, the critical section, which as described earlier is used to synchronize access to TConnectionModule instance reference counts, is created.

Next, the length of the dynamic array of IConnection references, FPool, is set to the number of available connections. This dynamic array is used to hold internal references to active connections (TConnectionModule instances), thereby preventing them from being released (until the TConnectionPool class is destroyed, or the cleanup thread determines that one or more of the connections have gone unused for an extended period of time).

Finally, an instance of the cleanup thread is created. This class is discussed in detail later in this article.

The most important method of the TConnectionPool class is the GetConnection method. This method returns an IConnection (implemented by TConnectionModule), so long as one is available (as controlled by the semaphore). The implementation of this method is shown here:

function TFixedConnectionPool.GetConnection: IConnection;
var
  i: Integer;
  DM: TConnectionModule;
  WaitResult: Integer;
begin
Result := nil;
WaitResult := WaitForSingleObject(Semaphore, FTimeout);
if WaitResult <> WAIT_OBJECT_0 then
  raise EConnPoolException.Create('Connection pool timeout. '+
    'Cannot obtain a connection');
CriticalSection.Enter;
try
  for i := Low(FPool) to High(FPool) do
    begin
      //If FPool[i] = nil, the IConnection has
      //not yet been created. Create it, initialize
      //it, and return it. If FPool[i] <> nil, then
      //check to see if its RefCount = 1 (only the pool
      //is referencing the object).
      if FPool[i] = nil then
        begin
          DM := TConnectionModule.Create(nil);
          DM.CriticalSection := Self.CriticalSection;
          DM.Semaphore := Self.Semaphore;
          FPool[i] := DM;
          FPool[i].Connection.Connected := True;
          Result := FPool[i];
          Exit;
        end;
      //if FPool[i].FRefCount = 1 then
      //the connection is available. Return it.
      if FPool[i].RefCount = 1 then
        begin
          Result := FPool[i];
          Exit;
        end;
    end; //for
finally
  CriticalSection.Leave;
end;
end;

As you can see from this code, when GetConnection is invoked, WaitForSingleObject is called using the connection pool’s semaphore. If a connection is available, WaitForSingleObject returns immediately, and the available count on the semaphore is reduced by one. If a connection is not currently available, the thread on which GetConnection is invoked is blocked until either a connection becomes available, or the connection timeout expires. If the connection timeout expires, an exception is raised.

When WaitForSingleObject returns Wait_Object_0, the thread invoking GetConnection is being granted access to the connection pool. This means that either there is one or more connections that have not yet been connected, or a previously connected connection is now available (its reference count is one).

This code then enters the critical section (since it might read the RefCount property of the connection module). It then iterates through the FPool dynamic array. It tests each element of this dynamic array for a value of nil, which signals that this connection has not yet been connected. If the element of FPool is nil, an instance of TConnectionModule is created and assigned to this array element (which increments its reference count to one). It is during this process that the critical section and semaphore reference of the connection pool object is passed to the connection module. Finally, the IConnection implementing object is returned (which increments its reference count to two).

Each time a given element of the dynamic array is found to be not nil, the loop next tests to see if the reference count of the current element is one. If it is one, that means the connection module was previously created and connected, but is not currently in use. In that case, that connection module is returned (which increments its reference count to two).

Once an available connection has returned, the critical section is exited.

Let’s consider the semaphore for a moment. When GetConnection is called, one of the available locks on the semaphore is taken when a connection can be obtained. This lock on the semaphore will be released back to the semaphore when the connection is no longer used by an external object (one outside the connection pool). This is signaled when the reference count decrements to one. This code was shown earlier in the TConnectionModule’s _Release method.

TCleanupThread

Just about all relevant code concerning this connection pool has been discussed, with the exception of the TCleanupThread class. This class implements a low priority thread that periodically wakes up and inspects the LastAccess property of all instances of the TConnectionModule class. While this operation is not essential for a connection pool, it permits a connection pool to limit the resources it uses on a database server by releasing connections when they are no longer being used.

The following is the declaration of the TClearnupThread class:

//This thread class is used by the connection pool
//object to cleanup idle connections after a
//configurable period of time.
TCleanupThread = class(TThread)
private
  FCleanupDelay: Integer;
protected
  //When the thread is created, this critical section
  //field will be assigned the connection pool's
  //critical section. This critical section is
  //used to synchronize access to data module
  //reference counts.
  CriticalSection: TCriticalSection;
  FixedConnectionPool: TFixedConnectionPool;
  procedure Execute; override;
  constructor Create(CreateSuspended: Boolean;
    const CleanupDelayMinutes: Integer);
end;

As you can see, the TCleanupThread class contains TCriticalSection and TFixedConnectionPool member fields. As you saw in the TFixedConnetionPool constructor shown earlier in this article, these members are assigned instances of the fixed connection pool’s critical section and a reference to the connection pool itself, respectively.

The following code shows the initialization of the TCleanupThread class in its constructor:

constructor TCleanupThread.Create(CreateSuspended: Boolean;
      const CleanupDelayMinutes: Integer);
begin
  // always create suspended
  inherited Create(True); // always create suspended
  FCleanupDelay := CleanupDelayMinutes;
  //Resume if not created suspended
  if not CreateSuspended then
    Resume;
end;

As you can see from this overloaded constructor, it begins by creating an instance of the thread as a suspended thread. It then stores the value of the ClearnupDelayMinutes formal parameter in a member field. Then, if the thread was created with a CreateSuspended formal parameter value of False, it resumes the thread.

The code in a thread is executed in that thread’s Execute method. The following is the Execute method of this thread:

procedure TCleanupThread.Execute;

var
  i: Integer;
begin
while True do
begin
  if Terminated then Exit;
  //sleep for delay
  sleep(FCleanupDelay * 1000 * 60);
  if Terminated then Exit;
  FixedConnectionPool.CriticalSection.Enter;
  try
    for i := low(FixedConnectionPool.FPool) to
      High(FixedConnectionPool.FPool) do
      //if the connection exists, has no external reference,
      //and has not been used lately, release it
      if (FixedConnectionPool.FPool[i] <> nil) and
        (FixedConnectionPool.FPool[i].RefCount = 1) and
        (MinutesBetween(FixedConnectionPool.FPool[i].LastAccess, Now) >
          FCleanupDelay) then
          FixedConnectionPool.FPool[i] := nil;
  finally
    FixedConnectionPool.CriticalSection.Leave;
  end;//try
end;//while
end;

When the thread executes, and after it verifies that it has not been terminate, it calls sleep for some number of minutes defined by the FCleanupDelay value. After the cleanup delay expires, the thread once again checks to see if it has been terminated, after which is enters the critical section and iterates through the array of IConnection references. For each connection that is not nil and whose reference count is not one, it checks to see if the connection has gone unused for greater than the cleanup delay interval. When an unused connection is found, the corresponding value of the IConnection dynamic array is set to nil, which causes the associated TConnectionModule object to be destroyed (through the interface reference count mechanism). This has the effect of closing the connection.

The TFixedConnectionPool Destructor

A number of resources are used by the TFixedConnectionPool class, including the semaphore and critical section. These need to be cleaned up when the fixed connection pool is destroyed. These tasks are performed by the overridden Destroy destructor of the TFixedConnectionPool class, as shown in the following implementation:

destructor TFixedConnectionPool.Destroy;
var
  i: Integer;
begin
  //Free any remaining connections
  CleanupThread.Terminate;
  CriticalSection.Enter;
  try
    for i := Low(FPool) to High(FPool) do
      FPool[i] := nil;
    SetLength(FPool,0);
  finally
    CriticalSection.Leave;
  end;
  CriticalSection.Free;
  //Release the semaphore
  CloseHandle(Semaphore);
  inherited;
end;

Here you see that the destructor begins by terminating the cleanup thread. Next, it enters the critical section and iterates through the connections in the connection pool, setting each to nil (thereby destroying the corresponding TConnectionModule instance). The IConnection dynamic array is then set to a size of zero. Finally, the critical section is exited, the critical section is freed, after which the handle of the semaphore closed.

Using the Fixed Connection Pool

Before you can use the TFixedConnectionPool class, you must invoke its constructor. This is shown in the following pseudo code:

var
  ConnPool: TFixedConnectionPool;

begin
  ConnPool := TFixedConnectionPool.Create(10, 5, 20000);

Here the connection pool is created with a maximum of 10 connections. Unused connections may be cleaned up after five minutes, and an exception will be raised if a connection cannot be obtained within 20 seconds.

The GetConnection method of the connection pool is used to return a connection module, which you must assign to an IConnection interface reference. You then use the returned interfaced object to obtain the actual connection by reading its connection property. This is shown in the following pseudo code:

var
  SQLDataSet: TSQLDataSet;
  Conn: IConnection;
begin
  SQLDataSet := TSQLDataSet.Create(nil);
  try
    SQLDataSet.CommandText := 'select * from employee';
    Conn := ConnPool.GetConnection;
    SQLDataSet.SQLConnection := Conn.Connection;
    SQLDataSet.Open;
    //do something with the result
  finally
    SQLDataSet.Free;
  end;
//The connection is released when Conn goes out of scope
end;

This article was adapted in part from Mastering Multithreading and Other Advanced Delphi Topics by Cary Jensen, one of the Delphi Developer Days 2003 Power Workshops, focused Delphi (TM) training.

Abstract: Semaphores are like mutexes on steroids. Not only can they coordinate multiple threads and process, but they can permit more than one simultaneous lock. This article shows you how to use these useful objects in a multithreaded environment

Semaphores are powerful synchronization objects that, like mutexes (mutually exclusives), permit you to coordinate multiple threads and processes in your Delphi applications. Likewise, in multithreaded server environments, such as WebSnap, Web Broker ISAPI servers, and IntraWeb applications, semaphores provide a flexible mechanism for protecting shared resources.

This article begins with brief introduction to synchronization. This is followed by a detailed look at using semaphores in your Delphi applications.

This article is part one of a two part series. In this article, the basic use of a semaphore is demonstrated. In part two, the use of a semaphore to implement a database connection pool is demonstrated.
Threads and Synchronization

Due to Delphi’s TThread class, it is relatively easy to create multithreaded applications. You create a TThread descendant using the Thread Object Wizard in Delphi’s Object Repository. You then implement this new class’s Execute method, placing in it the code that you want executed in the thread.

If this process is so easy, you might ask, then why don’t more Delphi developers make use of additional threads in their applications? When questioned about this, most developers point out that multithreaded applications are inherently more complex than single threaded applications.

In short, this complexity arises when two or more threads must access a common resource. Consider a single threaded application. When your code writes a value to a variable, and then, some time later, uses the value stored in that variable as a parameter to a procedure, you can be sure that the value in the variable is the very same value that was previously written.

This seems reasonable enough. However, if the application is multithreaded, and more than one thread can write a value to that variable, the assumption that a value assigned to a variable by code at one moment will be the value contained in that variable a little later is a dangerous one. In other words, some basic assumptions that are valid in a single threaded environment can lead to serious problems in a multithreaded environment.

Here is another example. Imagine that you write a function that opens a file handle, writes some data to the file, and then closes the file handle. In a single-threaded environment, calling this function will result in the writing of data to the file, and nothing else. In other words, between the initial invocation of the function and its return, the only operations that the application will perform are related to the writing of the data to the file.

Once again, in a multithreaded environment you cannot assume that between the invocation of a function and its return that only the function’s code is executed by your application. It is not only possible, but likely, that between the invocation of a function and its return, one or more other threads within the application may perform tasks. And unless you take precautions, it is possible that these other threads may interfere with the thread that is trying to write data to the file, either by compromising the data that is being written, the handle being used for the file, or by changing some other shared resource.

In a multithreaded environment it is important to remember that an individual thread has no control over when it will execute. In the pre-emptive multitasking environment of 32-bit Windows, it is the operating system that does this. Furthermore, the operating system has no notion of a unit of work being performed by a thread. If you need to ensure that a thread completes a unit of work before another thread that shares a common resource runs, you must take explicit steps to block any potentially disruptive threads until the unit of work is completed. This process is called synchronization.

For the most part, as you become acquainted with how threads work, and consider what units of works must not be interrupted by other threads, and learn to use appropriate technique to protect those units of work, you will find that multithreaded programming is really not much more complicated than single-threaded programming. In the end, its a matter of mindset. Like with most other problems in application development, once you know what to lookout for, and how to protect against potential problems, everything else will fall into place.
Understanding Semaphores

A semaphore, like a mutex, is an operating system-level object that you can use to synchronize your code. Like mutexes, semaphores can be used between threads in a single process as well as across processes. In fact, a semaphore that supports a maximum count of one serves essentially the same purpose as a mutex.

There is one very big difference between semaphores and mutexes, however. While a mutex can be acquired by no more than one thread or process at a time, semaphores can be designed to allow two or more threads to acquire the semaphore simultaneously.

This might not make sense at first. Specifically, synchronization is normally used to ensure that one and only one thread can obtain the synchronization object, thereby preventing its unit of work from being interrupted by another thread that shares some of the same resources. Doesn’t permitting two or more threads to access a common resource introduce instability?

The answer is no, so long as what is being synchronized by the semaphore can be used by two or more threads simultaneously. For example, consider a database connection pool. A database connection pool provides a set of database connections that can be shared by a population of threads. A semaphore is an ideal object for controlling access to a connection pool.

Here is how it works. Any time a thread needs to get a connection from the connection pool, it calls one of the Windows wait functions, passing the semaphore’s handle to the function. If a connection is available, the wait returns, and the semaphore’s available count is decremented. When the thread no longer needs the connection, it releases the semaphore, and the semaphore’s lock count is increased again.

So long as the configured maximum count of the semaphore is equal to or less than the number of available connections, the semaphore object ensures that any thread requesting a connection will be blocked if all connections are currently in use. A blocked thread will continue to be blocked until either a connection becomes available, or a timeout period expires.

You create a semaphore using the Windows API function CreateSemaphore. The following is the syntax of this function:

function CreateSemaphore(lpSemaphoreAttributes: PSecurityAttributes;
  lInitialCount: Integer; lMaximumCount: Integer ;
  lpName: PAnsiChar): Caradinal;

When you call CreateSemaphore, the first parameter that you pass is a pointer to a security attributes structure. To use the default security attributes, pass a value of nil.

The second parameter defines the initial count of the newly created semaphore, and the third parameter sets the maximum count. The second parameter must be a value between zero and the maximum count, and the third parameter must be greater than 1. If you pass a value of one in both the second and third parameters, the semaphore has one, and only one available lock (and it is not yet locked). The first thread to call a wait function for this semaphore will obtain the lock.

It is pretty common to set the second and third parameters to the same value. Doing so creates a semaphore will all of its locks currently available.

The fourth parameter is the name of the semaphore. The name is required if you want to be able to get a handle to the semaphore created in one process from a thread in another process. If you do not need to open this semaphore from another process, you can pass an empty string in this parameter.

Just as you can do with a mutex, you can attempt to get the handle of an existing semaphore by calling OpenSemaphore. This function has the following syntax:

function OpenSemaphore(dwDesiredAccess: Cardinal; bInheritHandle: LongBool;
  lpName: PAnsiChar): Cardinal;

When calling OpenSemaphore, you use the first parameter to identify the type of access that you want for the semaphore. Most developers pass the value SEMAPHORE_ALL_ACCESS. Use the second parameter to identify whether or not a process created by this process can inherit the handle to the mutex. If you pass True, a process created through a call to CreateProcess can inherit the mutex handle, otherwise it cannot.

The third parameter is the name of the semaphore. As is the case with mutexes, this name must be unique.

If OpenSemaphore is successful, it returns the handle of the semaphore. If OpenSemaphore fails, it returns 0. If OpenSemaphore returns 0, use GetLastError to determine the cause of the failure.

As mentioned earlier, a thread wishing to acquire the semaphore does so by calling one of the Windows wait functions. These functions include WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, WaitForMultipleObjectsEx, SignalObjectAndWait, MsgWaitForSingleObjects, and MsgWaitForMultipleObjectsEx.

The example project created later in this article makes use of WaitForSingleObject. This function has the following syntax:

function WaitForSingleObject(hHandle: Cardinal;
  dwMilliseconds: Cardinal): Cardinal;

When calling WaitForSingleObject, the first parameter that you pass is the handle of the semaphore that you obtained through a call to CreateSemaphore or OpenSemaphore, and the second parameter is the amount of time, in milliseconds, that you are willing to wait. If you never want the wait to timeout, pass the constant INFINITE in the second parameter.

If the semaphore has at least one count available, WaitForSingleObject succeeds immediately. In this case, the count of the semaphore is decremented by one, and WaitForSingleObject returns a value equal to the constant WAIT_OBJECT_0.

If the semaphore has no counts available, WaitForSingleObject will block the current thread until either a count becomes available, or the wait times out, which ever comes first. If a count became available, the count of the semaphore is again reduced by one, and WaitForSingleObject returns WAIT_OBJECT_0. If the wait timed out, WaitForSingleObject returns WAIT_TIMEOUT.

Because a successful call to one of the Wait functions decrements the count of a semaphore, it is important for a thread to release the semaphore as soon as it is through working with the shared resource. When a thread releases a semaphore, the semaphore’s count increments by one or more, thereby making the semaphore available to any other threads that are currently waiting for it.

You release a semaphore by calling ReleaseSemaphore. This function has the following syntax:

function ReleaseSemaphore(hSemaphore: Cardinal; lReleaseCount: Integer
  lpPreviousCount: Pointer): LongBool;

The first argument is the handle to the semaphore, and the second is the number of counts to add to the semaphore. A thread should only increment the semaphore’s count equal to the number of counts held by that thread. Normally, this will be equal to one.

The third parameter is a pointer to 32-bit variable that can be assigned the count of the semaphore prior to the release. If you do not need to know the semaphore’s previous count, pass nil in this third parameter.

All of the semaphore related functions and constants discussed in this section are declared in the Windows unit. Consequently, this unit must appear in the uses clause of any code that needs to use semaphores.
A Simple Semaphore Example

The following steps demonstrate how to create a simple project that demonstrates the use of a semaphore that can be locked multiple times.

1. Create a new project. Place on the main form a Panel and a ListBox from the Standard page of the component palette. Set the Align property of the Panel to alLeft.
2. Next place a Splitter (from the Advanced page of the Component palette). Its Align property should default to alLeft. Finally, set the ListBox’s Align property to alClient.
3. Place two Labels, two Edits, and two Buttons in the Panel. Set the Caption property of Button1 to Create Thread, and the Caption of Button2 to Clear ListBox.
4. Set the Caption of Label1 to Post Write Sleep (milliseconds), and the Label2 Caption to WaitFor Duration (milliseconds).
5. Set the Text property Edit1 to 2000, and the Text property of Edit2 to 1000. Finally, adjust the position and size of the components to look something like that shown in the following figure.

6. Select File | New | Other, and double-click the Thread Object Wizard on the New page of the Object Repository. Set Class Name to TGetSemWriteAndLeave.
7. Add both the Windows unit and the SysUtils unit to the interface section uses clause of the thread’s unit.
8. Modify the TGetSemWriteAndLeave class declaration to look like the following.

      type
        TGetSemWriteAndLeave = class(TThread)
        private
          { Private declarations }
          FSleepDuration: Integer;
          FWaitForDuration: Integer;
        protected
          WriteText: String;
          procedure Execute; override;
          procedure UpdateListBox;
        public
          property SleepDuration: Integer write FSleepDuration;
          property WaitForDuration: Integer write FWaitForDuration;
        end;

9. With your cursor on the class declaration in the editor, cress Ctrl-Shift-C to use class completion to generate the UpdateListBox method block in the implementation section.
10. Select File | Use Unit, and select the main form’s unit to add it to the thread unit’s uses clause.
11. Modify the UpdateListBox and Execute methods of the thread to look like the following:

      procedure   TGetSemWriteAndLeave.Execute;
      var
        WaitResult: Integer;
      begin
       WaitResult := WaitForSingleObject(Semaphore, FWaitForDuration);
        case WaitResult of
         WAIT_OBJECT_0: WriteText := 'Got it. Thread ID: '
           + IntToStr(Self.ThreadID);
         WAIT_TIMEOUT: WriteText := 'Timed out. Thread ID: '
           + IntToStr(Self.ThreadID);
         WAIT_ABANDONED: WriteText := 'Other. Thread ID: '
           + IntToStr(Self.ThreadID);
        end;
       Synchronize(UpdateListBox);
       sleep(FSleepDuration); //wait until releasing semaphore
       ReleaseSemaphore(Semaphore, 1, nil);
      end;

      procedure   TGetSemWriteAndLeave.UpdateListBox;
      begin
        Form1.ListBox1.Items.Add(WriteText);
      end;

12. Move to the main form’s unit. Update the interface var block to look like the following:

      var
        Form1: TForm1;
        Semaphore: THandle;

13. Select File | Use Unit from Delphi’s main menu, and select the thread’s unit.
14. Select the button labeled Create Thread and add the following OnClick event handler:

      procedure TForm1.Button1Click(Sender: TObject);
      begin
        with TGetSemWriteAndLeave.Create(True) do
        begin
         FreeOnTerminate := True;
         SleepDuration := StrToInt(Edit1.Text);
         WaitForDuration := StrToInt(Edit2.Text);
         Resume;
        end;
      end;

15. Select the button labeled Clear ListBox and add the following OnClick event handler:

      procedure TForm1.Button2Click(Sender: TObject);
      begin
        ListBox1.Items.Clear;
      end;

16. Finally, add the following initialization and finalization sections to the end of the main form’s unit, immediately prior to end.:

      initialization
        Semaphore := CreateSemaphore(nil, 3,3,'');

      finalization
        CloseHandle(Semaphore);

17. Run the project. Click the Create Thread button many times very quickly. After a short time, the list box will begin to display the messages from the threads, some of which indicate that they timed out waiting for the semaphore, as shown in the following figure.

As you can see from this project, while many of the threads where able to access the semaphore, some timed out before the semaphore was acquired. You might want to try this project with a variety of different post write sleep and waitfor duration values.

Article Created By : Cary Jensen

Hello all delphi.com readers, Lately I got a lot of job, and the deadline was very-very tight.So I Can not post too regularly so for you all delphi.com readers I apologize, you guys have to wait, life must go on right ?
Ok, now I want to share a trick on how we to measure the performance of one procedure or one syntax.

Let say that we have one syntax that we want to measure, let say it was the TStringList and then we want to know if this TStringList performance on sorting the text so let’s try..

don’t forget to uses this unit.

   uses
      Windows,SysUtils;

   procedure Testing;
   var a: TStrings;
        CountStart,CountStop:Int64;
   Begin
      a:= TStringList.Create;
      try
        a.Add('Test 1');
        a.Add('Coba1');
        a.Add('Lari1');
        a.Sorted:= True;
        QueryPerformanceCounter(CountStart);
        a.Sort;
        QueryPerformanceCounter(CounterStop);
        ShowMessage('Sorting Done in '+FloatToStr(((CounterStop-CounterStart)/CounterStart)*1000+'Miliseconds'));
      Finally
        a.Free;
      End;
   end;

So When the sorting is done..a pop up message will show to tell us how much milisecond was used to do the sorting. that way we can calculate which procedure from our source code that took big amount of process time and we can directly trimmed it down.Oh yes the QueryPerformanceCounter was an Windows Api function, and it was returning in nanoseconds so we need to multiply by 1000000 if we want in seconds also according to MSDN it uses Hardware timer so if your hardware not supporting it will return value 0.

So by this now we cant see which procedure or which syntax was taking so long to operate and we can find the best algorithm method to choose so over all our program will significantly increasing on the speed. Ok That’s all today happy testing and measuring..

Hi all delphi readers, have you all confront with this situation, imagine you have created some nice application with superb GUI (Graphical User Interface) but then when you do the final testing and review you find out that. Data that has longger length compare to DBGrid field length was castrate..that was very – very annoying. yeah ..I also think so i know this feeling because I’ve been there..
So enough let’s cut the crap..so let get to the point …below was the source code and idea so the DBGrid will adjust it self to the longgest length of the data when it was clicked.

procedure SetGridColumnWidths(Grid: Tdbgrid);
const
  DEFBORDER = 10;
var
  temp, n: Integer;
  lmax: array [0..30] of Integer;
begin
  with Grid do
  begin
    Canvas.Font := Font;
    for n := 0 to Columns.Count - 1 do
      lmax[n] := Canvas.TextWidth(Fields[n].FieldName) + DEFBORDER;
    grid.DataSource.DataSet.First;
    while not grid.DataSource.DataSet.EOF do
    begin
      for n := 0 to Columns.Count - 1 do
      begin
        temp := Canvas.TextWidth(trim(Columns[n].Field.DisplayText)) + DEFBORDER;
        if temp > lmax[n] then lmax[n] := temp;
      end; {for}
      grid.DataSource.DataSet.Next;
    end;
    grid.DataSource.DataSet.First;
    for n := 0 to Columns.Count - 1 do
      if lmax[n] > 0 then
        Columns[n].Width := lmax[n];
  end;
end; {SetGridColumnWidths  }

so we can insert this peace of code to any event you can think of …ex: OnClick event, OnShow event,etc just be creative. so hopefully this peace of code can help you all..

hi all delphi readers, You’ve seen this surely on web pages. Alternating table row colors means displaying the first record in one color and the second record in another color and continue to alternate the color of each row displayed.

When working with datasets with many rows, alternating the background color of each row can increase readability.
Alternating DBGrid Row Colors

Here’s the OnDrawColumnCell event handler for a DBGrid control to color every second row in a different color.

    procedure TGridForm.DBGridDrawColumnCell(
        Sender: TObject;
        const Rect: TRect;
        DataCol: Integer;
        Column: TColumn;
        State: TGridDrawState) ;
    var
      grid : TDBGrid;
      row : integer;
    begin
      grid := sender as TDBGrid;
      row := grid.DataSource.DataSet.RecNo;

      if Odd(row) then
        grid.Canvas.Brush.Color := clSilver
      else
        grid.Canvas.Brush.Color := clDkGray;

      grid.DefaultDrawColumnCell(Rect, DataCol, Column, State) ;
    end; (* DBGrid OnDrawColumnCell *)

Note that the row color eliminates the need of table borders and make it easy for the eye to read a row. In a vertical sense, the colors make it easier to ‘catch’ an item because it is on either one of the colors.

Of course, you need to take into consideration the color of the selected cell/row – I’ll leave this up to you – but this should help: Coloring Selected Rows

Play with the Options property to have the best looking grid for your Delphi application

Including (Linking/Embeding) Resources to Executables

With the Borland’s Resource Compiler we have created the AboutDelphi.res resource file. The next step is to add the following compiler directive to a unit in your project, immediately after the form directive (below the implementation key word).

{$R *.DFM} {$R AboutDelphi.RES}

Do not accidentally erase {$R *.DFM} part, as this is the line of code that tells Delphi to link in the form’s visual part. When you choose bitmaps for speed buttons, Image components or Button components, Delphi includes the bitmap file you chose as part of the form’s resource. Delphi isolates your user interface elements into the .DFM file.

After the .RES file is linked to the executable file, the application can load its resources at run time as needed. To actually use the resource, you’ll have to make a few Windows API calls.

In order to follow the article you’ll need a new Delphi project with a blank form (the default new project). Of course add the {$R AboutDelphi.RES} directive to the main form’s unit. It’s finally time to see how to use resources in a Delphi application. As mentioned above, in order to use resources stored inside an exe file we have to deal with API. However, several methods can be found in the Delphi help files that are “resource” enabled.

For example take a look at the LoadFromResourceName method of a TBitmap object. This method extracts the specified bitmap resource and assigns it TBitmap object. This is *exactly* what LoadBitmap API call does. As always Delphi has improved an API function call to suit your needs better.

Playing Animations from Resources

To show the animation inside the cool.avi (remember it was defined in the .rc file) we’ll use the TAnimate component (Win32 palette) – drop it on to the main form. Let the name of the Animate component be the default one: Animate1. We’ll use the OnCreate event of a form to display the animation:

    procedure TForm1.FormCreate(Sender: TObject) ;
    begin
       with Animate1 do begin
          ResName := 'cool';
          ResHandle := hInstance;
          Active := TRUE;
       end;
    end;

That simple! As we can see, in order to play an animation from a resource we have to use the use the ResHandle, ResName or ResID properties of TAnimate component. After setting ResHandle, we set the ResName property to specify which resource is the AVI clip that should be displayed by the animation control. Asigning True to the Active property simply starts the animation.

Playing WAVs

Since we have placed two WAVE files in our executable, we will now see how to grab a song inside the exe and play it. Drop a button (Button1) on a form and assign the following code to the OnClick event handler:

    uses mmsystem;

    procedure TForm1.Button1Click(Sender: TObject) ;
    var
       hFind, hRes: THandle;
       Song: PChar;
    begin
       hFind := FindResource(HInstance, 'MailBeep', 'WAVE') ;
       if hFind <> 0 then begin
          hRes:=LoadResource(HInstance, hFind) ;
          if hRes <> 0 then begin
            Song:=LockResource(hRes) ;
            if Assigned(Song) then SndPlaySound(Song, snd_ASync or snd_Memory) ;
            UnlockResource(hRes) ;
          end;
          FreeResource(hFind) ;
       end;
    end;

This approach uses several API calls to load a WAVE type resource named MailBeep and play it. Note: you cal use Delphi to play system predefined sounds.

Playing MP3s

Playing MP3s
The only MP3 file in our resource has the name Intro. Since this resource is of a RCDATA type we’ll use another technique to get and play the mp3 song. Yes, that’s right, the TMediaPlayer can play the mp3 file.

Now, add the TMediaPlayer component to a form (name: MediaPlayer1) and add a TButton (Button2). Let the OnClick event look like:

    procedure TForm1.Button2Click(Sender: TObject) ;
    var
       rStream: TResourceStream;
       fStream: TFileStream;
       fname: string;
    begin
       {this part extracts the mp3 from exe}
       fname := ExtractFileDir(Paramstr(0))+'\Intro.mp3';
       rStream := TResourceStream.Create(hInstance, 'Intro', RT_RCDATA) ;
       try
         fStream := TFileStream.Create(fname, fmCreate) ;
         try
           fStream.CopyFrom(rStream, 0) ;
         finally
           fStream.Free;
         end;
       finally
         rStream.Free;
       end;
       {this part plays the mp3}
       MediaPlayer1.Close;
       MediaPlayer1.FileName:=fname;
       MediaPlayer1.Open;
    end;

This code, with the help of TResourceStream, extracts the mp3 song from the exe and saves it to the applications working directory. The name of the mp3 file is intro.mp3. Then simply assign that file to the FileName property of a MediaPlayer and play the song.

One minor *problem* is that the application creates a mp3 song on a user machine. You could add a code that deletes that file before the application is terminated.

Extracting *.???

Of course every other type of a binary file can be stored as a RCDATA type. The TRsourceStream is designed specially to help us extract such file from an executable. The possibilities are endless: HTML in an exe, EXE in exe, empty database in an exe, ….
Back To Page 1

hi all delphi readers, Games and other types of applications which use multimedia files like sounds and animations must either distribute the extra multimedia files along with the application or embed the files within the executable.
Rather than distribute separate files for your application’s use, you can add the raw data to your application as a resource. You can then retrieve the data from your application when it is needed. This technique is generally more desirable because it can keep others from manipulating those add-in files.

This article will show you how to embed (and use) sound files, video clips, animations and more generally any kind of binary files in a Delphi executable. For the most general purpose you’ll see how to put a MP3 file inside a Delphi exe.

Resource Files (.RES)
we can use the Image Editor to create and edit resources that consist of such types of files. Now, when we are interested in storing various types of (binary) files inside a Delphi executable we’ll have to deal with resource script files (.rc), the Borland Resource Compiler tool and other.
Including several binary files in your executable consists of 5 steps:

1. Create and/or collect all the files you whish to put in an exe,
2. Create a resource script file (.rc) that describes those resources used by your application,
3. Compile the resource script file (.rc) file to create a resource file (.res),
4. Link the compiled resource file into the application’s executable file,
5. Use individual resource element.
The first step should be simple, simply decide what types of files you would like to store in you executable. For example, we will store two .wav songs, one .ani animations and one .mp3 song.

Before we move on, here are a few important statements concerning limitations when working with resources:

a) Loading and unloading resources is not a time consuming operation. Resources are part of the applications executable file and are loaded at the same time the application runs.

b) All the (free) memory can be used when loading/unloading resources. In other words there are no limits on number of resources loaded at the same time.

c)Of course, resource file do double the size of an executable. If you want smaller executable consider placing resources and parts of your project in DLLs and Packages.

Let’s now see how to create a file that describes resources.

Creating a Resource Script File (.RC)
A resource script file is a just a simple text file with the extension .rc that lists resources. The script file is in this format:

ResName1 ResTYPE1 ResFileName1
ResName2 ResTYPE2 ResFileName2
…
ResNameX ResTYPEX ResFileNameX
…

RexName specifies either a unique name or an integer value (ID) that identifies the resource. ResType describes the type of resource and the ResFileName is the full path and file name to the individual resource file.

To create a new resource script file, simply do the following:

1. Create a new text file in your projects directory.
2. Rename it to AboutDelphi.rc.

In the AboutDelphi.rc file, have the following lines:

Clock WAVE "c:\mysounds\projects\clock.wav"
MailBeep WAVE "c:\windows\media\newmail.wav"
Cool AVI cool.avi
Intro RCDATA introsong.mp3

The script file simply defines resources. Following the given format the AboutDelphi.rc script lists two .wav files, one .avi animation, and one .mp3 song. All statements in a .rc file associate an identifying name, type and file name for a given resource. There are about a dozen predefined resource types. These include icons, bitmaps, cursors, animations, songs, etc. The RCDATA defines generic data resources. RCDATA let you include a raw data resource for an application. Raw data resources permit the inclusion of binary data directly in the executable file. For example, the RCDATA statement above names the application’s binary resource Intro and specifies the file introsong.mp3, which contains the song for that mp3 file.

Note: make sure you have all the resources you list in your .rc file available. If the files are inside your projects directory you don’t have to include full file name. In my .rc file .wav songs are located *somewhere* on the disk and both the animation and mp3 song are located in the project’s directory.
Creating a Resource File (.RES)
To use the resources defined in the resource script file, we must compile it to a .res file with the Borland’s Resource Compiler. The resource compiler creates a new file based on the contents of the resource script file. This file usually has an .res extension. The Delphi linker will later reformat the .res file into a resource object file and then link it to the executable file of an application.

The Borland’s Resource Compiler command line tool is located in the Delphi Bin directory. The name is BRCC32.exe. Simply go to the command prompt and type brcc32 then press Enter. Since the Delphi\Bin directory is in your Path the Brcc32 compiler is invoked and displays the usage help (since it was called with no parapeters).

To compile the AboutDelphi.rc file to a .res file execute this command at the command prompt (in the projects directory):

BRCC32 AboutDelphi.RC

By default, when compiling resources, BRCC32 names the compiled resource (.RES) file with the base name of the .RC file and places it in the same directory as the .RC file.

You can name the resource file anything you want, as long as it has the extension “.RES” and the filename without the extension is not the same as any unit or project filename. This is important, because by default, each Delphi project that compiles into an application has a resource file with the same name as the project file, but with the extension .RES. It’s best to save the file to the same directory as your project file.
Go To Page 2

hi all delphi reader, today i want to share how to delete or sent files to recycle bin so after deletetion we can retrieve again the file.

Here’s a Delphi procedure that can delete a file with the ability to undo by sending the file to the “Recycle Bin. “Function bFileDelete” will return True if the operation was successful.

uses ShellAPI;

function bFileDelete(AFileName:string): boolean;
var    Struct: TSHFileOpStruct;
       pFromc: array[0..255] of char;
     Resultval: integer;
begin
   if not FileExists(AFileName) then begin
     Result := False;
     exit;
   end else begin
      fillchar(pfromc,sizeof(pfromc),0) ;
      StrPcopy(pfromc,expandfilename(AFileName)+#0#0) ;
      Struct.wnd := 0;
      Struct.wFunc := FO_DELETE;
      Struct.pFrom := pFromC;
      Struct.pTo := nil;
      Struct.fFlags:= FOF_ALLOWUNDO or FOF_NOCONFIRMATION or FOF_SILENT;
      Struct.fAnyOperationsAborted := false;
      Struct.hNameMappings := nil;
      Resultval := ShFileOperation(Struct) ;
      Result := (Resultval = 0) ;
   end;
end;

well hope that usefull for you all delphi readers.

hello, alldelphi.com reader todays tips is .. how to create a roll up form with animation. sure we now there are several component that can do that trick such as billenium and also one of the JEDI component. But surely if we can do it our self why buy or used another component right ?
so for the curiosity sake let see the code below..

type
   TForm1 = class(TForm)
   private
     fOldClientHeight: Integer;
     procedure WMNCRButtonDown(var Msg: TWMNCRButtonDown) ; message WM_NCRBUTTONDOWN;
   public

   end;

var
   Form1: TForm1;

implementation
{$R *.dfm}

procedure TForm1.WMNCRButtonDown(var Msg: TWMNCRButtonDown) ;
var
   h : integer;
begin
   if (Msg.HitTest = HTCAPTION) then
   begin
      if (ClientHeight = 0) then
      begin
         for h := 0 to fOldClientHeight do ClientHeight := h;
         Application.ProcessMessages;
      end  else
      begin
         fOldClientHeight := ClientHeight;
         for h := fOldClientHeight downto 0 do ClientHeight := h;
         Application.ProcessMessages;
      end;
   end;
end;

Well alldelphi.com readers hope it was usefull for you all