HEIDI's Programming Lab(s)

Installing Trac on the Bluehost or Hostmonster

noreply@blogger.com (Heshan Wanigasooriya) — Mon, 24 Nov 2008 16:29:32 PST

This guide was made primarily to help Hostmonster customers setup Trac. However, the setup is generic enough, that with only little modification, this guide can be applied to any shared-hosting setup running the Apache webserver (or if you want to use cgi for some reason). To work, you will need access to shell, and have basic understanding of text editing in shell. Hostmonster provides python2.3, and easy subversion repository setup - so these are assumed to already be in place.

Also, because I do not like the login hack described on the Hostmonster Trac Wiki, I have assumed that you will install one of the login plugins. However, if you have access to the Apache setup file and do not wish to use a login manager, you can use the account setup method outlined in the Trac wiki.

Full Story HEIDI Software;

Moving to New Host

noreply@blogger.com (Heshan Wanigasooriya) — Wed, 19 Nov 2008 14:02:04 PST

This Blog has been moved to HEIDI Software Labs

failed to open stream: HTTP request failed! HTTP/1.0 400 Bad Request

noreply@blogger.com (Heshan Wanigasooriya) — Thu, 13 Nov 2008 21:56:25 PST

Error:
copy(http://4.bp.blogspot.com/_YJxWEghlXts/SL6FjtRxdyI/AAAAAAAAAk8/TBCnJNEWgWs/s320/Photo 25.jpg) [function.copy]: failed to open stream: HTTP request failed! HTTP/1.0 400 Bad Request

Fixes :
This error can be occurred due to the bad URL format. In the above URL you can see "Photo 25.jpg", which has spaces between name, so that you have to fill them by urlencode() or just using str_replace().

Trac on DreamHost in 5 minutes

noreply@blogger.com (Heshan Wanigasooriya) — Fri, 07 Nov 2008 09:40:39 PST

Trac on DreamHost in 5 minutes

Installing Trac on DreamHost shared hosting is no easy task. Sure, there are some attempts to ease the pain, but they are half-done at best. So what I needed was a simple, automated, feature complete and easy to use way of installing Trac and managing my Trac projects on DreamHost.

After some search it turned out there's nothing out there that satisfies my needs. That's why I've took matters in my own hands and created the dreamy-trac open-source project.

Now, before installing we have to talk about...

Preconditions

To make all of that automatic goodness possible dreamy-trac makes some assumptions:

you are doing this on a working DreamHost account (best to create a new one),
you have shell access to that account,
all Subversion repositories you wish to expose to Trac are owned by that account,
all domains you wish to install Trac on are owned by that account,
all domains you wish to install Trac on have FastCGI enabled and
you understand what I've been talking about so far.

Installing Trac on DreamHost

Please note that the following instructions are for the latest stable version of dreamy-trac (0.11.1) at the moment of this writing - so YMMV.

Logon to the desired shell account and enter the following commands:

wget http://dreamy-trac.googlecode.com/files/dreamy-trac-0.11.1.tgz 
tar xzvf dreamy-trac-0.11.1.tgz
cd dreamy-trac
./configure.sh
source ~/.bash_profile
./install.sh

If Trac installed successfully you should be rewarded with the following message:

...lines omitted...
You have installed Trac. To create a new trac project run 'create_trac_project.'
Thank you for using dreamy-trac :)

Creating a new Trac project

You wouldn't believe how simple it is - just run create_trac_project, follow the instructions and the script will:

create a new Trac project,
setup permissions and create a superuser,
setup and use Account Manager plugin
setup the Subversion post-commit hook,
make your Trac project web accessible via FastCGI,
make your Trac project URLs pretty and
make Apache serve the static files instead of Trac.

DrupalCon in DC

noreply@blogger.com (Heshan Wanigasooriya) — Mon, 03 Nov 2008 23:13:46 PST

DrupalCon is the official Drupal unconference that attracts the most talented open source developers and innovative web shops in the world and brings them together to share knowledge, make decisions on the future of Drupal, and get to know each other in person.

It's also the premiere opportunity for Drupal users to learn what they can do with Drupal, find partners for future projects, and meet the people behind the code.

In this agenda you can see what the conference will focus on, and as you can see it's designed for both developers and Drupal users. The first three days of the conference will be about learning, while the last day will be about doing - that's when we'll all work together to push code and documentation forward.

DrupalCon is a volunteer run, nonprofit conference. Thanks to everyone who's helped and to our fantastic sponsors, who are letting us keep ticket prices low by paying for more than half of this event!

Quick look at the agenda

	Wednesday	Thursday	Friday	Saturday
1	Design and Usability	Code Development	Code Development	Code Sprint
2	Showcase and Strategy	Showcase and Strategy	Business Side	Documentation Sprint
3	Performance and Scalability	Code Development	Showcase and Strategy
4	Code Development	Drupal Community	Code Development

Fix HFS + Partition Error on dual boot Mac OS and Vista

noreply@blogger.com (Heshan Wanigasooriya) — Thu, 09 Oct 2008 20:27:09 PDT

This guide is for restoring our nice, working hackintosh's darwin bootloader.

Basically, Vista RTM foobars our working MBR's bootloader and you get "HFS+ partition error".
In following, I will assume we have one HDD with two partitions: part#1 = OSX and part#2 = Vista

1. Boot off OSX dvd disc in single user mode (press F8 and type -s)
2. At single user prompt
fdisk -e /dev/rdisk0
flag 1
update
write
quit
4 reboot

At this point OSX should boot up, just like prior to Vista installation.
1 In a terminal window,
su root
fdisk -e /dev/rdisk0
flag 2
quit
2 reboot

Vista will say "\Window\system32\winload" corrupted, and it will tell you to insert Vista disc and recover.
Follow directions from Vista and recover, then reboot. Check Vista boots and works fine.

1. Boot off OSX dvd disc for single user one last time (press F8 and type -s)
2. At single user prompt
fdisk -e /dev/rdisk0
flag 1
quit
3. reboot

Dual Boot { Kalyway | iAtkos | Leo4all | Jas | iDeneb } 10.5.2 to 10.5.5 MAC OSX86 Leopard + Vista Installation gu

noreply@blogger.com (Heshan Wanigasooriya) — Mon, 06 Oct 2008 07:31:05 PDT

This guide will show you how to make a Dual Boot 10.5.X OSX86 System with WINDOWS VISTA . Use this guide with your favourite distro { Kalyway iAtkos Leo4all Jas iDeneb }

Personally I found Kalyway and iAtkos more effective than other distro's.

1 . First of all you have to install Vista. It's easy and I m sure that you are familiar with it.
2 . Partitioning have an vital role so take care of it for installing OSX you need to have a partition of minimum 10 gb. The partition must be formatted as FAT-32 Primary Partition.

You can use Partition Magic for partitiong also.

3 . Boot into Windows installation and open Command Prompt { Start < All Program < Accessories < Command prompt } With Administrative Privillage and run following commands.

4 . In command prompt typeDISKPART and press enter. Now you are in DISKPART utility . So here we are using DISKPART for making HFS compatible Partition.

*Command*	*Preface*
DISKPART> list disk	" This will show you a list of selectable disks. "

DISKPART> select disk n	[where n = the disk number]
	This will specify which disk to create a new partition on
DISKPART> create partition primary size=n id=af	[where n = the size in MB of the partition, For 20 gb space n will be 20000 ] [where af = hfs+ compatible]
	Will proceed to create a bootable primary partition for the Mac
DISKPART> list partition	" This command will show you the partitions on your selected disk "

DISKPART> select partition n	[where n = the newly created OSX partition]
	This will specify the partition
DISKPART> active	" This will make your OS X partition the first-boot active partition "

DISKPART> Exit	Exit from DiskPart...........

5 .In Windows Vista you must disable User Account Control [ UAC ].
6 . Put your DVD in rom and restart your computer with the DVD in Drive,now you should see Darwin load screen.
7 . As counting starts press F8 key and you will be able to have some more option's.
8 . Now type –V and press enter now enterd in VERBOSE mode here you are able to see any error if your screen freezes for more than 15 minutes than note last three lines and google them to find out a solution for your problem. If every thing goes fine after 15-30 minutes installation screen appear's hold your breath we are not quit yet here.
9 . On the top a menu bar appears click Utilities .
10 . Here select the destination drive where u want to install Mac OSX.
11 . Now click on ERASE on right hand side and under the format option select" MAC OSX Journaled Extended " and click Erase. Now the disk will be erased and mounted once this done you are very near to near to your destination.
12 . Now close the disk utility and click on the partition which you created at previous
Step.
13 . Now your disk will be checked for consistency than installaion begins. It will take 30-45 minute's as your hardware.
14 . Once the installation finishes . click on restart with the DVD inside in drive.Don't remove the disk.
15 .. computer restart's don't click anything even you see the boot screen. Yes you done it enjoy……….
___________________________________________________________

Now you have two option's Boot with Darwin Bootloader or use VISTA bootloader.

______________________________________________________

For Darwin bootloader follow these instruction.

Darwin has its own dual-boot menu which is easy to activate, just press F8 on your keyboard before the Darwin boot loader prompt and Apple boot logo.The dual-boot menu might appear by itself depending on whether or not the install disc automatically sets the time-out period for you.
If you want to create a time-out that will allow you to select which OS to boot from without pressing F8, follow these instructions:

Firstly, load up Terminal (Applications/Utilities/) from within OS X, then type:

sudo nano /Library/Preferences/SystemConfiguration/com.apple.Boot.plist

edit the Darwin time-out

flag accordingly:

<key>Timeout</key>
<string>8</string>

Press CTRL+O and then Enter to save the file, after which you can safely close the session by pressing CTRL+X.

- x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x

For VISTA bootloader use this guide .

Put the Vista Installation Disc into your DVD drive and restart to boot from it. Click Repair System, press next and then select Command Prompt Type DISKPART and press Enter.

Command	Preface
DISKPART> list disk	" This will show you a list of selectable disks. "

DISKPART> select disk n	[where n = the disk number]
	Select the disk which Windows Vista is installed to
DISKPART> list partition	This will show you the partitions on your selected disk

DISKPART> select partition n	[where n = the Windows Vista partition]
	This will specify the partition
DISKPART> active	Will make your Windows Vista partition the first-boot active partition

DISKPART> Exit	Exit from DiskPart...........

Reboot into Windows Vista.
Next, you can either follow the command line BCDEDIT instructions below, or use EasyBCD.

Copy CHAIN0 from your Mac OS X partition or Installation Disc to the root of your Vista partition C:\.

- x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x

For Vista Bootloader you can also use BCD-EDIT.

1) Boot into Vista. Copy the chain0 file from the Leopard DVD to C:

2) Open the "Command prompt" with "Elevated Admin" privileges from the Start Menu.

3) Type the following into the prompt

bcdedit /copy {current} /d "Mac OS X"

bcdedit /enum active
bcdedit /set {GUID} PATH \chain0

4) In the first command type {current} as it is, literally..nothing else..just {current} with the brackets. In the 3rd command however, replace the {GUID} with the alphanumeric GUID you see in the enumerated list under MAC OS X. You can see this list on your terminal as soon as you type the 2nd command above.

5) Close the Command Prompt and Restart Vista.

6) You Should now be looking at a screen with two options to boot into Mac OSX or Vista.

Select Mac OSX to see if you can boot into it. You should see the familiar Darwin boot Loading screen with the timer going down. If you dont do anything, then it counts to zero and again shows the menu screen with Vista and MAC OSX options. Dont panic!

Again select MAC OS X, and now as the timer counts down, Press F8. You would see a list of partitions on your disk with their names. Select the partition with MAC OSX installed by using up/down arrows and press ENTER.

- x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x – x –

If you find this guide useful to you than digg it for raisimg my moral………………..

Speed Test on Dialog HSDPA

noreply@blogger.com (Heshan Wanigasooriya) — Mon, 29 Sep 2008 05:18:50 PDT

Apple iPhone

noreply@blogger.com (Heshan Wanigasooriya) — Sun, 28 Sep 2008 02:32:58 PDT

http://www.youtube.com/watch?v=YgW7or1TuFk

Launched a new Firefox extetntion - FireImage

noreply@blogger.com (Heshan Wanigasooriya) — Sat, 27 Sep 2008 06:08:40 PDT

I fortunate to contribute for Firefox extension development,as a one of my project on rent a coder.
It was very interesting idea for me to continue working night and day. The buyer also gave me a nice help on all the way that he can.

OFFICIAL WEBSITE : www.keeimages.com

DOWNLOAD THE Add-On : FireImage v1.0

Their requirement was :

A Firefox plug in/add on where users right click on an image they see on the web and save it to an image website. Can be done when registered also. You need to build the website as well as the plug in/add on.

Step By Step functionality

A user installs the Firefox plugin.

They are at a website where they see an image they like.

They right click on the image and select 'save image to website'

A pop-up box comes up with 'name your file' and they name it and hit ok

a pop-up box comes up with 'add tags' they enter tags and hit ok

The image is than uploaded to the server in the background with a scrambled file name like dsfs7d6fshdsfs5.jpg and the file name the user entered and tags are associated with the file in the database.

the file is saved to a page eg. website.com/images/scrabmedtext/ which is my website template with the image, filename and tags in the content area.

(in the user's perspective, the last thing they did was add their tags and hit ok.

a box appears in front of the user with the url to this page mentioned above where they can copy it.

-----------------

If the user is registered to the website they enter their details into the plugins preferences. username and password.

If the details are correct, the user can d the samer as above, however they get a page www.website.com/username/ where the user's images are, in a stream from newest to oldest, in a blog type format. 5 images per page. Users have the option to log into the site and delete the image, change the title or add/remove tags.

The site needs a basic template, with a header, left right and bottom as php includes. I can change everything.

Site needs to be powered by php and well commented

I need an admin panel, where I can delete certain images or accounts. I also need to be able to see total amount of registred accounts. I need to be able to set a max mb limit for images.

---------------

Server info:

images are saved as a scrambled filename in their original format.
saved to a certain folder eg. website.com/img/ - there can be scrambled dirs after that if need be as you cannot have millions of files in one directory - but the original file is the identifier.

---------------

I could come-up with a nice solution that impressed by the buyer.

OFFICIAL WEBSITE : www.keepaa.com

DOWNLOAD THE Add-On : FireImage v1.0

Please let me know if any bug or security issue found .

PHP recursive directory remove function

noreply@blogger.com (Heshan Wanigasooriya) — Thu, 04 Sep 2008 06:11:39 PDT

Validate Email address in JS and RE

noreply@blogger.com (Heshan Wanigasooriya) — Tue, 12 Aug 2008 00:18:53 PDT

<script language="javascript">
function checkEmail() {
var email = document.getElementById(’emailaddress’);
var filter  = /^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$/;
if (!filter.test(email.value)) {
alert(’Please provide a valid email address’);
email.focus
return false;
}
}
</script>code>Heshan Wanigasooriya



How to create and remove directory / folder in PHP
noreply@blogger.com (Heshan Wanigasooriya) — Mon, 11 Aug 2008 23:23:01 PDT
Remove directory

$mydir = '/path/directory/images/'; // this will remove images directory
if (is_dir($mydir)) {
rmdir($mydir);
} else {
echo $mydir.' does not exists';
}

Create
$mydir = '/path/directory/images/
mkdir($mydir);Heshan Wanigasooriya

 



New theme Design for Drupal 5.xx
noreply@blogger.com (Heshan Wanigasooriya) — Wed, 23 Jul 2008 22:32:36 PDT
A new theme has launched by me for the Drupal CMS.
screen shots are available here and contact me if you want to  download it.
This will publish very soon in the Drual site.
Hesh












Heshan Wanigasooriya

 



Logo Launched for rent a coder
noreply@blogger.com (Heshan Wanigasooriya) — Sun, 20 Jul 2008 10:34:02 PDT
Heshan Wanigasooriya

 



How to bypass proxy server
noreply@blogger.com (Heshan Wanigasooriya) — Sun, 20 Jul 2008 09:06:50 PDT
Most network administrators at work, university or school deny access to certain websites, instant messaging or social networks such as facebook, myspace or orkut with a firewall or proxy server. If you are constantly getting a message saying “Can’t connect” or something similar, the service you are trying to connect to have probably been blocked by your network administrator.

The same is the case with my college LAN where most of the things are blocked and even many institutional sites are not accessible. Damn it! But as soon as the system is made, next day it’s broken. That’s the way we suppose to live.

So, it’s time to focus on our main topic- how to bypass firewalls, proxy servers and hide IP address.

Software Requirements
1- HOPSTER -> Download and Install. 

Visit here for help.

---- OR ----

1- JAP -> Download and Install. 


2- Java Runtime Enviroment(JRE) -> Download and Install.


There is an open source utility called JAP that protects our privacy on the Internet. In process to this it also helps to bypass firewalls and proxy servers.

Instead of connecting directly to a webserver, users take a detour, connecting with encryption through several intermediaries, so-called Mixes. JAP uses a predetermined sequence for the mixes. Such a sequence of linked mixes is called a Mix Cascade. Users can choose between different mix cascades.

Since many users use these intermediaries at the same time, the internet connection of any one single user is hidden among the connections of all the other users. No one, not anyone from outside, not any of the other users, not even the provider of the intermediary service can determine which connection belongs to which user.

Let’s learn how to configure it. Just follow the steps:-

1- After installation, open JAP and click on “Config” button.
Photobucket

A “Settings” window will get opened.

2- Click on “Network” and if you are using any proxy to connect to the Internet then enter your proxy details under “Proxy/Firewall” section. Don’t forget to choose type of the proxy you are having.
Photobucket

3- Next, choose “Services” under “Anonymity” option.

4- Click on the “Reload” button and after few minutes you’ll get a list of services called “Mix Cascades and single Mixes”

It is through these services we will get connected to the Internet, bypass the firewall and surf anonymously. It’s important to first understand these different types of services before start using it. There are basically 3 types of services that may be available to you at a given time. First one is the paid one, second is free services and third is the test service.

We will be focusing on Free Services here. Now how to recognize which service is of what type?

5- From the dropdown list above select “Mix cascades without costs“.

6- Now the RED stop mark before a service name shows it is “excluded by filter” which means it’s a paid service. But a BLUE ball mark before a service name shows it’s free to use.

7- Choose any one of the available free services and click on the “Select” button to activate it.
Photobucket

Free Services that I prefer are “Dresden-Dresden” or “SpeedParter-ULD”

8- Click “OK”.

That’s it. You are all set to connect to the Internet now.

9- Set Anonymity to “On“.
Photobucket

Soon JAP will get connected. Now, let’s learn how to use it.

To make web applications ( like Internet Explorer, YM, GTalk etc) work with JAP, use “IP address” 127.0.0.1 and “port number” 4001 under connection settings of your applications.

(If this particular part is not clear, please ask your doubts in comments section of this post)

ALL DONE!!!

No more blocked web sites, no more blocked IMs. Everything is unblocked now that too with certain level of anonymity. Isn’t great?Heshan Wanigasooriya

 



Drupal Programming from an Object-Oriented Perspective
noreply@blogger.com (Heshan Wanigasooriya) — Sun, 13 Jul 2008 02:26:41 PDT
Drupal Programming from an Object-Oriented Perspective


    Drupal often gets criticized by newcomers who believe that
    object-oriented programming (OOP) is always the best way to design software
    architecture, and since they do not see the word "class" in the Drupal
    code, it must be inferior to other solutions. In fact, it is true that
    Drupal does not use many of the OOP features of PHP, but it is a mistake to
    think that the use of classes is synonymous with object-oriented design.
    This article will cover several of the features of Drupal from an
    object-oriented perspective, so programmers comfortable with that paradigm
    can begin to feel at home in the Drupal code base, and hopefully be able to
    choose the right tool for the job.


    Motivations for Current Design


    As of version 4.6, Drupal does not use PHP's     href="http://www.php.net/manual/en/language.oop.php#keyword.class">class
    construct. This decision was made for several reasons.


    First, PHP's support for object-oriented constructs was much less
    mature at the time of Drupal's design. Drupal was built on PHP 4, and most
    of the improvements in PHP 5 relate to its     href="http://www.php.net/manual/en/migration5.oop.php">object-oriented
    features.


    Second, Drupal code is highly compartmentalized into modules, each of
    which defines its own set of functions. The inclusion of files is handled
    inside functions as well; PHP's performance suffers if all code is included
    on each page call, so Drupal attempts to load as little code as possible
    per request. This is a critical consideration, especially in the absence of
    a PHP
    accelerator; the act of compiling the code accounts for more than half
    of a Drupal page request. Functions are therefore defined inside other
    functions in Drupal, with respect to the runtime scope. This is perfectly
    legal. However, PHP does not allow the same kind of nesting with class
    declarations. This means that the inclusion of files defining classes must
    be "top-level," and not inside any function, which leads either to slower
    code (always including the files defining classes) or a large amount of
    logic in the main index.php file.


    Finally, using classes to implement Drupal constructs is difficult due
    to the use of some advanced object-oriented design patterns used by Drupal
    itself. While this may sound self-contradictory, it should become clear in
    the following discussion that the lack of certain OOP constructs such as     href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_7.html">Objective-C's
    "categories" in PHP would mean that implementing some Drupal mechanisms
    (such as the theme
    system) would be more complicated using classes than using
    functions.


    OOP Concepts in Drupal


    Despite the lack of explicitly-declared classes in Drupal, many
    object-oriented paradigms are still used in its design. There are many sets
    of "essential features" that are said to be necessary to classify a system
    as object-oriented; we will look at one of the     href="http://en.wikipedia.org/wiki/Object-oriented_programming">more
    popular definitions and examine some ways in which Drupal exhibits
    those characteristics.


    Objects


    There are many constructs in Drupal that fit the description of an
    "object". Some of the more prominent Drupal components that could be
    considered objects are modules, themes, nodes, and users.


    Nodes are the basic content building blocks of a Drupal site, and
    bundle together the data that makes up a "page" or "story" on a typical
    site. The methods that operate on this object are defined in node.module,
    usually called by the node_invoke() function. User objects similarly
    package data together, bringing together information about each account on
    the site, profile information, and session tracking. In both cases, the
    data structure is defined by a database table instead of a class. Drupal
    exploits the relational nature of its supported databases to allow other
    modules to extend the objects with additional data fields.


    Modules and themes are object-like as well, filling the "controller"
    role in many ways. Each module is a source file, but also bundles together
    related functions and follows a pattern of defining Drupal hooks.


    Abstraction


    Drupal's hook
    system is the basis for its interface abstraction. Hooks define the
    operations that can be performed on or by a module. If a module implements
    a hook, it enters into a contract to perform a particular task when the
    hook is invoked. The calling code need not know anything else about the
    module or the way the hook is implemented in order to get useful work done
    by invoking the hook.


    Encapsulation


    Like most other object-oriented systems, Drupal does not have a way of
    strictly limiting access to an object's inner workings, but rather relies
    on convention to accomplish this. Since Drupal code is based around
    functions, which share a single namespace, this namespace is subdivided by
    the use of prefixes. By following this simple convention, each module can
    declare its own functions and variables without the worry of conflict with
    others.


    Convention also delineates the public API of a class from its internal
    implementation. Internal functions are prefixed by an underscore to
    indicate that they should not be called by outside modules. For example,
    _user_categories() is a private function which is subject to change without
    notice, while user_save() is part of the public interface to the user
    object and can be called with the expectation that the user object will be
    saved to the database (even though the method of doing this is
    private).


    Polymorphism


    Nodes are polymorphic in the classical sense. If a module needs to
    display a node, for example, it can call node_view() on that node to get an
    HTML representation. The actual rendering, though, will depend on which
    type of node is passed to the function; this is directly analogous to
    having the class of an object determine its behavior when a message is sent
    to it. Drupal itself handles the same introspection tasks required of an
    OOP language's runtime library.


    Furthermore, the rendering of the node in this example can be affected
    by the active theme. Themes are polymorphic in the same way; the theme is
    passed a "render this node" message, and responds to it in a different way
    depending on the implementation of the active theme, though the interface
    is constant.


    Inheritance


    Modules and themes can define whatever functions they please. However,
    they can both be thought to inherit their behavior from an abstract base
    class. In the case of themes, the behavior of this class is determined by
    the functions in theme.inc; if a theme does not override a function defined
    there, the default rendering of an interface component is used, but the
    theme can instead provide its own rendering. Modules similarly have the
    selection of all Drupal hooks to override at will, and may pick and choose
    which ones to implement.


    Design Patterns in Drupal


    Much of Drupal's internal structure is more complicated than simple
    inheritance and message passing, however. The more interesting features of
    the system result from using established software design patterns. Many of
    the patterns detailed in the seminal Gang of Four     href="http://en.wikipedia.org/wiki/Design_Patterns">Design Patterns
    book can be observed in Drupal, for instance.


    Singleton


    If we are to think of modules and themes as objects, then they follow
    the singleton pattern. In general these objects do not encapsulate data;
    what separates one module from another is the set of functions it contains,
    so it should be thought of as a class with a singleton instance.


    Decorator


    Drupal makes extensive use of the decorator pattern. The polymorphism
    of node objects was discussed earlier, but this is only a small piece of
    the power of the node system. More interesting is the use of
    hook_nodeapi(), which allows arbitrary modules to extend the behavior of
    all nodes. 


    This feature allows for a wide variety of behaviors to be added to
    nodes without the need for subclassing. For instance, a basic story node
    has only a few pieces of associated data: title, author, body, teaser, and
    a handful of metadata. A common need is for files to be uploaded and
    attached to a node, so one could design a new node type that had the story
    node's features plus the ability to attach files. Drupal's upload module
    satisfies this need in a much more modular fashion by using nodeAPI to
    grant every node that requests it the ability to have attached files.


    This behavior could be imitated by the use of decorators, wrapping them
    around each node object. More simply, languages that support categories,
    like Objective-C, could augment the common base class of all node objects
    to add the new behavior. Drupal's implementation is a simple ramification
    of the hook system and the presence of node_invoke_all().


    Observer


    The above interaction is also similar to the use of observers in
    object-oriented systems. This Observer pattern is pervasive throughout
    Drupal. When a modification is made to a vocabulary in Drupal's taxonomy
    system, the taxonomy hook is called in all modules that implement it. By
    implementing the hook, they have registered as observers of the vocabulary
    object; any changes to it can then be acted on as is appropriate.


    Bridge


    The Drupal     href="http://api.drupal.org/api/group/database">database abstraction
    layer is implemented in a fashion similar to the Bridge design pattern.
    Modules need to be written in a way that is independent of the database
    system being used, and the abstraction layer provides for this. New
    database layers can be written that conform to the API defined by the
    bridge, adding support for additional database systems without the need to
    modify module code.


    Chain of Responsibility


    Drupal's menu
    system follows the Chain of Responsibility pattern. On each page
    request, the menu system determines whether there is a module to handle the
    request, whether the user has access to the resource requested, and which
    function will be called to do the work. To do this, a message is passed to
    the menu item corresponding to the path of the request. If the menu item
    cannot handle the request, it is passed up the chain. This continues until
    a module handles the request, a module denies access to the user, or the
    chain is exhausted.


    Command


    Many of Drupal's hooks use the Command pattern to reduce the number of
    functions that are necessary to implement, passing the operation as a
    parameter along with the arguments. In fact, the hook system itself uses
    this pattern, so that modules do not have to define every hook, but rather
    just the ones they care to implement.


    Why Not to Use Classes


    The above hopefully clarifies the ways in which Drupal embodies various
    OOP concepts. Why, then, doesn't Drupal move in the direction of using
    classes to solve these problems in the future? Some of the reasons are
    historical, and were discussed earlier. Others, though, become clearer now
    that we have stepped through some of the design patterns used in
    Drupal.


    A good example is the extensibility of the theme system. A theme
    defines functions for each of the interface elements it wants to display in
    a special way. As noted earlier, this makes themes seem like a good
    candidate to inherit from an abstract base class that defines the default
    rendering of the elements.


    What happens, though, when a module is added that adds a new interface
    element? The theme should be able to override the rendering of this element
    as well, but if a base class is defined, the new module has no way of
    adding another method to that class. Complicated patterns could be set up
    to emulate this behavior, but Drupal's theme architecture quite elegantly
    handles the situation using its own function dispatch system. In this case
    and others like it, the classes that on the surface simplify the system end
    up serving to make it more cumbersome and difficult to extend.


    Room for Improvement


    While Drupal does reflect many object-oriented practices, there are some
    aspects of OOP that could be brought to bear on the project in more
    powerful ways.


    Encapsulation, while adequate in theory, is not applied consistently
    enough across the code base. Modules should more rigorously define which
    functions are public and which are private; the tendency right now is to
    publish most functions in the public namespace even if the interface is
    volatile. This problem is exacerbated by Drupal's policy of forgoing
    backward compatibility in exchange for cleaner APIs whenever necessary.
    This policy has led to some very good code, but would need to be excercised
    much less often if better encapsulation conventions were followed.


    Inheritance is also weak in the system. While, as noted above, all
    modules share a common set of behavior, it is difficult to extend this to
    new modules. One can create new modules easily that augment the behavior of
    existing ones, but there is not a way to override just some of a module's
    behavior. The impact of this can be marginalized by breaking large modules
    into smaller "a la carte" bundles of functionality, so that undesired
    aspects of a module may be more easily left out of the system.


    Other Paradigms


    Drupal is on the surface a procedural system, because it is built in a
    procedural language (PHP without classes). The paradigm behind a piece of
    software is not entirely dependent on its representation in code, however.
    Drupal is not afraid to borrow concepts from many disparate programming
    paradigms where it is convenient. A great deal of the power of Drupal comes
    from its underlying relational database, and relational programming
    techniques that mirror it. The fact that Drupal's work, much like that of
    any web application, consists of many reactions to discrete and rapid page
    requests should make the behavior of the system resonate with proponents of
    event-driven programming. To an aspect-oriented programmer, the invocation
    of hooks in arbitrary modules may look strikingly similar to a pointcut.
    And, as should be abundantly clear by now, Drupal is no stranger to
    object-oriented concepts either.
Heshan Wanigasooriya

 



heshanonline launched
noreply@blogger.com (Heshan Wanigasooriya) — Wed, 11 Jun 2008 20:44:23 PDT
Hi All
I have launched my new personnel web site www.heshanonline.tk.
Give your feedback,
-HeshanHeshan Wanigasooriya

 



DBD::mysql - MySQL driver for the Perl5 Database Interface (DBI)
noreply@blogger.com (Heshan Wanigasooriya) — Sat, 10 May 2008 07:13:45 PDT
NAME 
  DBD::mysql - MySQL driver for the Perl5 Database Interface (DBI)
  SYNOPSIS 
      use DBI;

   $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port";

   $dbh = DBI->connect($dsn, $user, $password);


   $drh = DBI->install_driver("mysql");
   @databases = DBI->data_sources("mysql");
      or
   @databases = DBI->data_sources("mysql",
                                  {"host" => $host, "port" => $port});

   $sth = $dbh->prepare("SELECT * FROM foo WHERE bla");
      or
   $sth = $dbh->prepare("LISTFIELDS $table");
      or
   $sth = $dbh->prepare("LISTINDEX $table $index");
   $sth->execute;
   $numRows = $sth->rows;
   $numFields = $sth->{'NUM_OF_FIELDS'};
   $sth->finish;

   $rc = $drh->func('createdb', $database, $host, $user, $password, 'admin');
   $rc = $drh->func('dropdb', $database, $host, $user, $password, 'admin');
   $rc = $drh->func('shutdown', $host, $user, $password, 'admin');
   $rc = $drh->func('reload', $host, $user, $password, 'admin');

   $rc = $dbh->func('createdb', $database, 'admin');
   $rc = $dbh->func('dropdb', $database, 'admin');
   $rc = $dbh->func('shutdown', 'admin');
   $rc = $dbh->func('reload', 'admin');
  EXAMPLE 
    #!/usr/bin/perl

 use strict;
 use DBI();

 # Connect to the database.
 my $dbh = DBI->connect("DBI:mysql:database=test;host=localhost",
                        "joe", "joe's password",
                        {'RaiseError' => 1});

 # Drop table 'foo'. This may fail, if 'foo' doesn't exist.
 # Thus we put an eval around it.
 eval { $dbh->do("DROP TABLE foo") };
 print "Dropping foo failed: $@\n" if $@;

 # Create a new table 'foo'. This must not fail, thus we don't
 # catch errors.
 $dbh->do("CREATE TABLE foo (id INTEGER, name VARCHAR(20))");

 # INSERT some data into 'foo'. We are using $dbh->quote() for
 # quoting the name.
 $dbh->do("INSERT INTO foo VALUES (1, " . $dbh->quote("Tim") . ")");

 # Same thing, but using placeholders
 $dbh->do("INSERT INTO foo VALUES (?, ?)", undef, 2, "Jochen");

 # Now retrieve data from the table.
 my $sth = $dbh->prepare("SELECT * FROM foo");
 $sth->execute();
 while (my $ref = $sth->fetchrow_hashref()) {
   print "Found a row: id = $ref->{'id'}, name = $ref->{'name'}\n";
 }
 $sth->finish();

 # Disconnect from the database.
 $dbh->disconnect();
  DESCRIPTION 
  DBD::mysql is the Perl5 Database Interface driver for the MySQL database. In other words: DBD::mysql is an interface between the Perl programming language and the MySQL programming API that comes with the MySQL relational database management system. Most functions provided by this programming API are supported. Some rarely used functions are missing, mainly because noone ever requested them. :-)
  In what follows we first discuss the use of DBD::mysql, because this is what you will need the most. For installation, see the sections on INSTALLATION, and "WIN32 INSTALLATION" below. See EXAMPLE for a simple example above.
  From perl you activate the interface with the statement
      use DBI;
  After that you can connect to multiple MySQL database servers and send multiple queries to any of them via a simple object oriented interface. Two types of objects are available: database handles and statement handles. Perl returns a database handle to the connect method like so:
    $dbh = DBI->connect("DBI:mysql:database=$db;host=$host",
                     $user, $password, {RaiseError => 1});
  Once you have connected to a database, you can can execute SQL statements with:
    my $query = sprintf("INSERT INTO foo VALUES (%d, %s)",
                     $number, $dbh->quote("name"));
 $dbh->do($query);
  See DBI(3) for details on the quote and do methods. An alternative approach is
    $dbh->do("INSERT INTO foo VALUES (?, ?)", undef,
          $number, $name);
  in which case the quote method is executed automatically. See also the bind_param method in DBI(3). See "DATABASE HANDLES" below for more details on database handles.
  If you want to retrieve results, you need to create a so-called statement handle with:
    $sth = $dbh->prepare("SELECT * FROM $table");
 $sth->execute();
  This statement handle can be used for multiple things. First of all you can retreive a row of data:
    my $row = $sth->fetchrow_hashref();
  If your table has columns ID and NAME, then $row will be hash ref with keys ID and NAME. See "STATEMENT HANDLES" below for more details on statement handles.
  But now for a more formal approach:
Heshan Wanigasooriya

 



How does MediaWiki work?
noreply@blogger.com (Heshan Wanigasooriya) — Sat, 10 May 2008 07:08:07 PDT

       From MediaWiki.org
                      
  
 
 You probably know Wikipedia, the free encyclopedia, and may possibly be a little bit confused by similar, but different, words such as Wiki, Wikimedia or MediaWiki.
 To avoid a possible confusion between the words you may first want to read the article about the names where the differences are explained.
 
 General Overview
    
 MediaWiki can be used in large enterprise server farms as in the Wikimedia Foundation cluster.
 
 
 MediaWiki is free server-based software which is licensed under the GNU General Public License (GPL). It's designed to be run on a large server farm for a website that gets millions of hits per day. MediaWiki is an extremely powerful, scaleable software and a feature-rich wiki implementation, that uses PHP to process and display data stored in its MySQL database.
 Pages use MediaWiki's wikitext format, so that users without knowledge of XHTML or CSS can edit them easily.
 When a user submits an edit to a page, MediaWiki writes it to the database, but without deleting the previous versions of the page, thus allowing easy reverts in case of vandalism or spamming. MediaWiki can manage image and multimedia files, too, which are stored in the filesystem. For large wikis with lots of users, MediaWiki supports caching and can be easily coupled with Squid proxy server software.
 
 Try out Wikitext
    
 Basic wikitext (wiki markup)
 
 
 Yes, you can easily modify pages and you can (temporarily) publish dummy sentences, and you can even (temporarily) completely destroy a page in a wiki. You don't need to have any programming skills to do this.
 We suggest you exercise yourself within our sandbox.
 You can also look up the cheat sheet with basic formatting commands.
Heshan Wanigasooriya

 



Access Parents Variables from Child Thread + Perl
noreply@blogger.com (Heshan Wanigasooriya) — Thu, 08 May 2008 00:18:28 PDT
NAME
 threads::shared - Perl extension for sharing data structures between threads
 VERSION
 This document describes threads::shared version 1.14
 SYNOPSIS
   use threads;
 use threads::shared;
   my $var :shared;
 $var = $scalar_value;
 $var = $shared_ref_value;
 $var = share($simple_unshared_ref_value);
   my ($scalar, @array, %hash);
 share($scalar);
 share(@array);
 share(%hash);
 my $bar = &share([]);
 $hash{bar} = &share({});
   { lock(%hash); ...  }
   cond_wait($scalar);
 cond_timedwait($scalar, time() + 30);
 cond_broadcast(@array);
 cond_signal(%hash);
   my $lockvar :shared;
 # condition var != lock var
 cond_wait($var, $lockvar);
 cond_timedwait($var, time()+30, $lockvar);
 DESCRIPTION
 By default, variables are private to each thread, and each newly created thread gets a private copy of each existing variable.  This module allows you to share variables across different threads (and pseudo-forks on Win32).  It is used together with the threads module.
 EXPORT
 share , cond_wait , cond_timedwait , cond_signal , cond_broadcast , is_shared 
 Note that if this module is imported when threads has not yet been loaded, then these functions all become no-ops.  This makes it possible to write modules that will work in both threaded and non-threaded environments.
 FUNCTIONS
 share VARIABLE share  takes a value and marks it as shared. You can share a scalar, array, hash, scalar ref, array ref, or hash ref.  share  will return the shared rvalue, but always as a reference.
 A variable can also be marked as shared at compile time by using the :shared  attribute: my $var :shared; .
 Due to problems with Perl's prototyping, if you want to share a newly created reference, you need to use the &share([])  and &share({})  syntax.
 The only values that can be assigned to a shared scalar are other scalar values, or shared refs:
   my $var :shared;
 $var = 1;              # ok
 $var = [];             # error
 $var = &share([]);     # ok
 share  will traverse up references exactly one level.  share(\$a)  is equivalent to share($a) , while share(\\$a)  is not.  This means that you must create nested shared data structures by first creating individual shared leaf nodes, and then adding them to a shared hash or array.
   my %hash :shared;
 $hash{'meaning'} = &share([]);
 $hash{'meaning'}[0] = &share({});
 $hash{'meaning'}[0]{'life'} = 42;
 
is_shared VARIABLE is_shared  checks if the specified variable is shared or not.  If shared, returns the variable's internal ID (similar to refaddr()).  Otherwise, returns undef.
   if (is_shared($var)) {
     print("\$var is shared\n");
 } else {
     print("\$var is not shared\n");
 }
 
lock VARIABLE lock places a lock on a variable until the lock goes out of scope.  If the variable is locked by another thread, the lock call will block until it's available.  Multiple calls to lock by the same thread from within dynamically nested scopes are safe -- the variable will remain locked until the outermost lock on the variable goes out of scope.
 Locking a container object, such as a hash or array, doesn't lock the elements of that container. For example, if a thread does a lock(@a), any other thread doing a lock($a[12]) won't block.
 lock() follows references exactly one level.  lock(\$a) is equivalent to lock($a), while lock(\\$a) is not.
 Note that you cannot explicitly unlock a variable; you can only wait for the lock to go out of scope.  This is most easily accomplished by locking the variable inside a block.
   my $var :shared;
 {
     lock($var);
     # $var is locked from here to the end of the block
     ...
 }
 # $var is now unlocked
 If you need more fine-grained control over shared variable access, see Thread::Semaphore.
 
cond_wait VARIABLE 
cond_wait CONDVAR, LOCKVAR The cond_wait  function takes a locked variable as a parameter, unlocks the variable, and blocks until another thread does a cond_signal  or cond_broadcast  for that same locked variable.  The variable that cond_wait  blocked on is relocked after the cond_wait  is satisfied.  If there are multiple threads cond_wait ing on the same variable, all but one will re-block waiting to reacquire the lock on the variable. (So if you're only using cond_wait  for synchronisation, give up the lock as soon as possible). The two actions of unlocking the variable and entering the blocked wait state are atomic, the two actions of exiting from the blocked wait state and re-locking the variable are not.
 In its second form, cond_wait  takes a shared, unlocked variable followed by a shared, locked variable.  The second variable is unlocked and thread execution suspended until another thread signals the first variable.
 It is important to note that the variable can be notified even if no thread cond_signal  or cond_broadcast  on the variable.  It is therefore important to check the value of the variable and go back to waiting if the requirement is not fulfilled.  For example, to pause until a shared counter drops to zero:
   { lock($counter); cond_wait($count) until $counter == 0; }
 
cond_timedwait VARIABLE, ABS_TIMEOUT 
cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR In its two-argument form, cond_timedwait  takes a locked variable and an absolute timeout as parameters, unlocks the variable, and blocks until the timeout is reached or another thread signals the variable.  A false value is returned if the timeout is reached, and a true value otherwise.  In either case, the variable is re-locked upon return.
 Like cond_wait , this function may take a shared, locked variable as an additional parameter; in this case the first parameter is an unlocked condition variable protected by a distinct lock variable.
 Again like cond_wait , waking up and reacquiring the lock are not atomic, and you should always check your desired condition after this function returns.  Since the timeout is an absolute value, however, it does not have to be recalculated with each pass:
   lock($var);
 my $abs = time() + 15;
 until ($ok = desired_condition($var)) {
     last if !cond_timedwait($var, $abs);
 }
 # we got it if $ok, otherwise we timed out!
 
cond_signal VARIABLE The cond_signal  function takes a locked variable as a parameter and unblocks one thread that's cond_wait ing on that variable. If more than one thread is blocked in a cond_wait  on that variable, only one (and which one is indeterminate) will be unblocked.
 If there are no threads blocked in a cond_wait  on the variable, the signal is discarded. By always locking before signaling, you can (with care), avoid signaling before another thread has entered cond_wait().
 cond_signal  will normally generate a warning if you attempt to use it on an unlocked variable. On the rare occasions where doing this may be sensible, you can suppress the warning with:
   { no warnings 'threads'; cond_signal($foo); }
 
cond_broadcast VARIABLE The cond_broadcast  function works similarly to cond_signal . cond_broadcast , though, will unblock all the threads that are blocked in a cond_wait  on the locked variable, rather than only one.
 
 OBJECTS
 threads::shared exports a version of bless REF that works on shared objects such that blessings propagate across threads.
   # Create a shared 'foo' object
 my $foo;
 share($foo);
 $foo = &share({});
 bless($foo, 'foo');
   # Create a shared 'bar' object
 my $bar;
 share($bar);
 $bar = &share({});
 bless($bar, 'bar');
   # Put 'bar' inside 'foo'
 $foo->{'bar'} = $bar;
   # Rebless the objects via a thread
 threads->create(sub {
     # Rebless the outer object
     bless($foo, 'yin');
      # Cannot directly rebless the inner object
     #bless($foo->{'bar'}, 'yang');
       # Retrieve and rebless the inner object
     my $obj = $foo->{'bar'};
     bless($obj, 'yang');
     $foo->{'bar'} = $obj;
   })->join();
  print(ref($foo),          "\n");    # Prints 'yin'
 print(ref($foo->{'bar'}), "\n");    # Prints 'yang'
 print(ref($bar),          "\n");    # Also prints 'yang'
 NOTES
 threads::shared is designed to disable itself silently if threads are not available. If you want access to threads, you must use threads  before you use threads::shared .  threads will emit a warning if you use it after threads::shared.
 BUGS AND LIMITATIONS
 When share  is used on arrays, hashes, array refs or hash refs, any data they contain will be lost.
   my @arr = qw(foo bar baz);
 share(@arr);
 # @arr is now empty (i.e., == ());
   # Create a 'foo' object
 my $foo = { 'data' => 99 };
 bless($foo, 'foo');
   # Share the object
 share($foo);        # Contents are now wiped out
 print("ERROR: \$foo is empty\n")
     if (! exists($foo->{'data'}));
 Therefore, populate such variables after declaring them as shared.  (Scalar and scalar refs are not affected by this problem.)
 It is often not wise to share an object unless the class itself has been written to support sharing.  For example, an object's destructor may get called multiple times, once for each thread's scope exit.  Another danger is that the contents of hash-based objects will be lost due to the above mentioned limitation.  See examples/class.pl (in the CPAN distribution of this module) for how to create a class that supports object sharing.
 Does not support splice on arrays!
 Taking references to the elements of shared arrays and hashes does not autovivify the elements, and neither does slicing a shared array/hash over non-existent indices/keys autovivify the elements.
 share()  allows you to share($hashref->{key})  without giving any error message.  But the $hashref->{key}  is not shared, causing the error "locking can only be used on shared values" to occur when you attempt to lock($hasref->{key}).
 View existing bug reports at, and submit any new bugs, problems, patches, etc. to: http://rt.cpan.org/NoAuth/Bugs.html?Dist=threads-shared
 SEE ALSO
 threads::shared Discussion Forum on CPAN: http://www.cpanforum.com/dist/threads-shared
 Annotated POD for threads::shared: http://annocpan.org/~JDHEDDEN/threads-shared-1.14/shared.pm
 Source repository: http://code.google.com/p/threads-shared/
 threads, perlthrtut
 http://www.perl.com/pub/a/2002/06/11/threads.html and http://www.perl.com/pub/a/2002/09/04/threads.html
 Perl threads mailing list: http://lists.cpan.org/showlist.cgi?name=iThreads
 AUTHOR
 Artur Bergman 
 threads::shared is released under the same license as Perl.
 Documentation borrowed from the old Thread.pm.
 CPAN version produced by Jerry D. Hedden .
Heshan Wanigasooriya

 



This brief tutorial will outline how to enable file sharing in Ubuntu.
noreply@blogger.com (Heshan Wanigasooriya) — Mon, 21 Apr 2008 02:35:45 PDT
 
  Sharing files and folders across your network from your Ubuntu PC is every bit as easy as sharing files in Windows (arguably, it’s easier). Start by right-clicking the folder you want to share, and select Share Folder. If the services required to share files/folders aren’t installed, you’ll be prompted to install them. 
 After clicking Install services they will automatically start to download and install. 
 Once that has completed you’ll be presented with an options window. From here you can select the type of sharing (SMB or NFS), give the shared folder a name and decide if you want read-only access to the folder. Click OK when you’re done.
 If you right-click on your newly shared folder and select Properties and then the Emblems tab, you can give the folder a unique icon so you’ll know it’s shared.  

click to enlarge
 You can further modify the permissions of your shared folder by selecting the Permissions tab. 

click to enlarge
 Now open a terminal in Ubuntu and enter the command:
 sudo smbpasswd -a username 
 This will add a SMB user.  
 And now other computers can connect to your shared folder!  
 
Heshan Wanigasooriya

 



Split
noreply@blogger.com (Heshan Wanigasooriya) — Thu, 17 Apr 2008 21:46:45 PDT

 
    A very useful function in Perl is split, which splits up a string and places it into an array. The function uses a regular expression and as usual works on the $_ variable unless otherwise specified.  
  The split function is used like this: 
$info = "Caine:Michael:Actor:14, Leafy Drive";
@personal = split(/:/, $info);
 which has the same overall effect as @personal = ("Caine", "Michael", "Actor", "14, Leafy Drive");
 If we have the information stored in the $_ variable then we can just use this instead @personal = split(/:/);
    If the fields are divided by any number of colons then we can use the RE codes to get round this. The code 
$_ = "Capes:Geoff::Shot putter:::Big Avenue";
@personal = split(/:+/);
 is the same as @personal = ("Capes", "Geoff",
            "Shot putter", "Big Avenue");
 But this: $_ = "Capes:Geoff::Shot putter:::Big Avenue";
@personal = split(/:/);
 would be like @personal = ("Capes", "Geoff", "",
            "Shot putter", "", "", "Big Avenue");
    A word can be split into characters, a sentence split into words and a paragraph split into sentences: 
@chars = split(//, $word);
@words = split(/ /, $sentence);
@sentences = split(/\./, $paragraph);
 In the first case the null string is matched between each character, and that is why the @chars array is an array of characters - ie an array of strings of length 1.Heshan Wanigasooriya

 



Perl Functions A-Z
noreply@blogger.com (Heshan Wanigasooriya) — Tue, 08 Apr 2008 09:40:54 PDT
A
abs - absolute value function
accept - accept an incoming socket connect
alarm - schedule a SIGALRM 
atan2 - arctangent of Y/X in the range -PI to PI
B
bind - binds an address to a socket
binmode - prepare binary files for I/O
bless - create an object 
break - 
C
caller - get context of the current subroutine call
chdir - change your current working directory
chmod - changes the permissions on a list of files
chomp - remove a trailing record separator from a string
chop - remove the last character from a string
chown - change the owership on a list of files
chr - get character this number represents
chroot - make directory new root for path lookups
close - close file (or pipe or socket) handle
closedir - close directory handle
connect - connect to a remote socket
continue - optional trailing block in a while or foreach 
cos - cosine function
crypt - one-way passwd-style encryption
D
dbmclose - breaks binding on a tied dbm file
dbmopen - create binding on a tied dbm file
defined - test whether a value, variable, or function is defined
delete - deletes a value from a hash
die - raise an exception or bail out
do - turn a BLOCK into a TERM
dump - create an immediate core dump
E
each - retrieve the next key/value pair from a hash
endgrent - be done using group file
endhostent - be done using hosts file
endnetent - be done using networks file
endprotoent - be done using protocols file
endpwent - be done using passwd file
endservent - be done using services file
eof - test a filehandle for its end
eval - catch exceptions or compile and run code
exec - abandon this program to run another
exists - test whether a hash key is present
exit - terminate this program
exp - raise I to a power
F
fcntl - file control system call
fileno - return file descriptor from filehandle
flock - lock an entire file with an advisory lock
fork - create a new process just like this one
format - declare a picture format with use by the write() function
formline - internal function used for formats
G
getc - get the next character from the filehandle
getgrent - get next group record 
getgrgid - get group record given group user ID
getgrnam - get group record given group name
gethostbyaddr - get host record given its address
gethostbyname - get host record given name
gethostent - get next hosts record 
getlogin - return who logged in at this tty
getnetbyaddr - get network record given its address
getnetbyname - get networks record given name
getnetent - get next networks record 
getpeername - find the other end of a socket connection
getpgrp - get process group
getppid - get parent process ID
getpriority - get current nice value
getprotobyname - get protocol record given name
getprotobynumber - get protocol record numeric protocol
getprotoent - get next protocols record
getpwent - get next passwd record
getpwnam - get passwd record given user login name
getpwuid - get passwd record given user ID
getservbyname - get services record given its name
getservbyport - get services record given numeric port
getservent - get next services record 
getsockname - retrieve the sockaddr for a given socket
getsockopt - get socket options on a given socket
glob - expand filenames using wildcards
gmtime - convert UNIX time into record or string using Greenwich time
goto - create spaghetti code
grep - locate elements in a list test true against a given criterion
H
hex - convert a string to a hexadecimal number
I
import - patch a module's namespace into your own
index - find a substring within a string
int - get the integer portion of a number
ioctl - system-dependent device control system call
J
join - join a list into a string using a separator
K
keys - retrieve list of indices from a hash
kill - send a signal to a process or process group
L
last - exit a block prematurely
lc - return lower-case version of a string
lcfirst - return a string with just the next letter in lower case
length - return the number of bytes in a string
link - create a hard link in the filesytem
listen - register your socket as a server 
local - create a temporary value for a global variable (dynamic scoping)
localtime - convert UNIX time into record or string using local time
lock - get a thread lock on a variable, subroutine, or method
log - retrieve the natural logarithm for a number
lstat - stat a symbolic link
M
m - match a string with a regular expression pattern
map - apply a change to a list to get back a new list with the changes
mkdir - create a directory
msgctl - SysV IPC message control operations
msgget - get SysV IPC message queue
msgrcv - receive a SysV IPC message from a message queue
msgsnd - send a SysV IPC message to a message queue
my - declare and assign a local variable (lexical scoping)
N
next - iterate a block prematurely
no - unimport some module symbols or semantics at compile time
O
oct - convert a string to an octal number
open - open a file, pipe, or descriptor
opendir - open a directory
ord - find a character's numeric representation
our - declare and assign a package variable (lexical scoping)
P
pack - convert a list into a binary representation
package - declare a separate global namespace
pipe - open a pair of connected filehandles
pop - remove the last element from an array and return it
pos - find or set the offset for the last/next m//g search
print - output a list to a filehandle
printf - output a formatted list to a filehandle
prototype - get the prototype (if any) of a subroutine
push - append one or more elements to an array
Q
q - singly quote a string
qq - doubly quote a string
qr - Compile pattern 
quotemeta - quote regular expression magic characters
qw - quote a list of words
qx - backquote quote a string
R
rand - retrieve the next pseudorandom number 
read - fixed-length buffered input from a filehandle
readdir - get a directory from a directory handle
readline - fetch a record from a file
readlink - determine where a symbolic link is pointing
readpipe - execute a system command and collect standard output
recv - receive a message over a Socket
redo - start this loop iteration over again
ref - find out the type of thing being referenced
rename - change a filename
require - load in external functions from a library at runtime
reset - clear all variables of a given name
return - get out of a function early
reverse - flip a string or a list
rewinddir - reset directory handle
rindex - right-to-left substring search
rmdir - remove a directory
S
s - replace a pattern with a string
say - 
scalar - force a scalar context
seek - reposition file pointer for random-access I/O
seekdir - reposition directory pointer 
select - reset default output or do I/O multiplexing
semctl - SysV semaphore control operations
semget - get set of SysV semaphores
semop - SysV semaphore operations
send - send a message over a socket
setgrent - prepare group file for use
sethostent - prepare hosts file for use
setnetent - prepare networks file for use
setpgrp - set the process group of a process
setpriority - set a process's nice value
setprotoent - prepare protocols file for use
setpwent - prepare passwd file for use
setservent - prepare services file for use
setsockopt - set some socket options
shift - remove the first element of an array, and return it
shmctl - SysV shared memory operations
shmget - get SysV shared memory segment identifier
shmread - read SysV shared memory 
shmwrite - write SysV shared memory 
shutdown - close down just half of a socket connection
sin - return the sine of a number
sleep - block for some number of seconds
socket - create a socket
socketpair - create a pair of sockets
sort - sort a list of values 
splice - add or remove elements anywhere in an array
split - split up a string using a regexp delimiter
sprintf - formatted print into a string 
sqrt - square root function
srand - seed the random number generator
stat - get a file's status information
state - 
study - optimize input data for repeated searches
sub - declare a subroutine, possibly anonymously
substr - get or alter a portion of a stirng
symlink - create a symbolic link to a file
syscall - execute an arbitrary system call
sysopen - open a file, pipe, or descriptor
sysread - fixed-length unbuffered input from a filehandle
sysseek - position I/O pointer on handle used with sysread and syswrite
system - run a separate program 
syswrite - fixed-length unbuffered output to a filehandle
T
tell - get current seekpointer on a filehandle
telldir - get current seekpointer on a directory handle
tie - bind a variable to an object class 
tied - get a reference to the object underlying a tied variable
time - return number of seconds since 1970
times - return elapsed time for self and child processes
tr - transliterate a string
truncate - shorten a file
U
uc - return upper-case version of a string
ucfirst - return a string with just the next letter in upper case
umask - set file creation mode mask
undef - remove a variable or function definition
unlink - remove one link to a file
unpack - convert binary structure into normal perl variables
unshift - prepend more elements to the beginning of a list
untie - break a tie binding to a variable
use - load in a module at compile time
utime - set a file's last access and modify times
V
values - return a list of the values in a hash
vec - test or set particular bits in a string
W
wait - wait for any child process to die
waitpid - wait for  a particular child process to die
wantarray - get void vs scalar vs list context of current subroutine call
warn - print debugging info
write - print a picture record
X
-X - a file test (-r, -x, etc)
Y
y - transliterate a string
Heshan Wanigasooriya

 



tutorial on threads in Perl
noreply@blogger.com (Heshan Wanigasooriya) — Tue, 08 Apr 2008 01:10:32 PDT
NAME
 perlthrtut - tutorial on threads in Perl
  
 DESCRIPTION
     WARNING: Threading is an experimental feature.  Both the interface
   and implementation are subject to change drastically.  In fact, this
   documentation describes the flavor of threads that was in version
   5.005.  Perl 5.6.0 and later have the beginnings of support for
   interpreter threads, which (when finished) is expected to be
   significantly different from what is described here.  The information
   contained here may therefore soon be obsolete.  Use at your own risk!
 One of the most prominent new features of Perl 5.005 is the inclusion of threads.  Threads make a number of things a lot easier, and are a very useful addition to your bag of programming tricks.
  
 What Is A Thread Anyway?
 A thread is a flow of control through a program with a single execution point.
 Sounds an awful lot like a process, doesn't it? Well, it should. Threads are one of the pieces of a process.  Every process has at least one thread and, up until now, every process running Perl had only one thread.  With 5.005, though, you can create extra threads.  We're going to show you how, when, and why.
  
 Threaded Program Models
 There are three basic ways that you can structure a threaded program.  Which model you choose depends on what you need your program to do.  For many non-trivial threaded programs you'll need to choose different models for different pieces of your program.
  
Boss/Worker
 The boss/worker model usually has one `boss' thread and one or more `worker' threads.  The boss thread gathers or generates tasks that need to be done, then parcels those tasks out to the appropriate worker thread.
 This model is common in GUI and server programs, where a main thread waits for some event and then passes that event to the appropriate worker threads for processing.  Once the event has been passed on, the boss thread goes back to waiting for another event.
 The boss thread does relatively little work.  While tasks aren't necessarily performed faster than with any other method, it tends to have the best user-response times.
  
Work Crew
 In the work crew model, several threads are created that do essentially the same thing to different pieces of data.  It closely mirrors classical parallel processing and vector processors, where a large array of processors do the exact same thing to many pieces of data.
 This model is particularly useful if the system running the program will distribute multiple threads across different processors.  It can also be useful in ray tracing or rendering engines, where the individual threads can pass on interim results to give the user visual feedback.
  
Pipeline
 The pipeline model divides up a task into a series of steps, and passes the results of one step on to the thread processing the next.  Each thread does one thing to each piece of data and passes the results to the next thread in line.
 This model makes the most sense if you have multiple processors so two or more threads will be executing in parallel, though it can often make sense in other contexts as well.  It tends to keep the individual tasks small and simple, as well as allowing some parts of the pipeline to block (on I/O or system calls, for example) while other parts keep going.  If you're running different parts of the pipeline on different processors you may also take advantage of the caches on each processor.
 This model is also handy for a form of recursive programming where, rather than having a subroutine call itself, it instead creates another thread.  Prime and Fibonacci generators both map well to this form of the pipeline model. (A version of a prime number generator is presented later on.)
  
 Native threads
 There are several different ways to implement threads on a system.  How threads are implemented depends both on the vendor and, in some cases, the version of the operating system.  Often the first implementation will be relatively simple, but later versions of the OS will be more sophisticated.
 While the information in this section is useful, it's not necessary, so you can skip it if you don't feel up to it.
 There are three basic categories of threads-user-mode threads, kernel threads, and multiprocessor kernel threads.
 User-mode threads are threads that live entirely within a program and its libraries.  In this model, the OS knows nothing about threads.  As far as it's concerned, your process is just a process.
 This is the easiest way to implement threads, and the way most OSes start.  The big disadvantage is that, since the OS knows nothing about threads, if one thread blocks they all do.  Typical blocking activities include most system calls, most I/O, and things like sleep().
 Kernel threads are the next step in thread evolution.  The OS knows about kernel threads, and makes allowances for them.  The main difference between a kernel thread and a user-mode thread is blocking.  With kernel threads, things that block a single thread don't block other threads.  This is not the case with user-mode threads, where the kernel blocks at the process level and not the thread level.
 This is a big step forward, and can give a threaded program quite a performance boost over non-threaded programs.  Threads that block performing I/O, for example, won't block threads that are doing other things.  Each process still has only one thread running at once, though, regardless of how many CPUs a system might have.
 Since kernel threading can interrupt a thread at any time, they will uncover some of the implicit locking assumptions you may make in your program.  For example, something as simple as $a = $a + 2 can behave unpredictably with kernel threads if $a is visible to other threads, as another thread may have changed $a between the time it was fetched on the right hand side and the time the new value is stored.
 Multiprocessor Kernel Threads are the final step in thread support.  With multiprocessor kernel threads on a machine with multiple CPUs, the OS may schedule two or more threads to run simultaneously on different CPUs.
 This can give a serious performance boost to your threaded program, since more than one thread will be executing at the same time.  As a tradeoff, though, any of those nagging synchronization issues that might not have shown with basic kernel threads will appear with a vengeance.
 In addition to the different levels of OS involvement in threads, different OSes (and different thread implementations for a particular OS) allocate CPU cycles to threads in different ways.
 Cooperative multitasking systems have running threads give up control if one of two things happen.  If a thread calls a yield function, it gives up control.  It also gives up control if the thread does something that would cause it to block, such as perform I/O.  In a cooperative multitasking implementation, one thread can starve all the others for CPU time if it so chooses.
 Preemptive multitasking systems interrupt threads at regular intervals while the system decides which thread should run next.  In a preemptive multitasking system, one thread usually won't monopolize the CPU.
 On some systems, there can be cooperative and preemptive threads running simultaneously. (Threads running with realtime priorities often behave cooperatively, for example, while threads running at normal priorities behave preemptively.)
  
 What kind of threads are perl threads?
 If you have experience with other thread implementations, you might find that things aren't quite what you expect.  It's very important to remember when dealing with Perl threads that Perl Threads Are Not X Threads, for all values of X.  They aren't POSIX threads, or DecThreads, or Java's Green threads, or Win32 threads.  There are similarities, and the broad concepts are the same, but if you start looking for implementation details you're going to be either disappointed or confused.  Possibly both.
 This is not to say that Perl threads are completely different from everything that's ever come before--they're not.  Perl's threading model owes a lot to other thread models, especially POSIX.  Just as Perl is not C, though, Perl threads are not POSIX threads.  So if you find yourself looking for mutexes, or thread priorities, it's time to step back a bit and think about what you want to do and how Perl can do it.
  
 Threadsafe Modules
 The addition of threads has changed Perl's internals substantially.  There are implications for people who write modules--especially modules with XS code or external libraries.  While most modules won't encounter any problems, modules that aren't explicitly tagged as thread-safe should be tested before being used in production code.
 Not all modules that you might use are thread-safe, and you should always assume a module is unsafe unless the documentation says otherwise.  This includes modules that are distributed as part of the core.  Threads are a beta feature, and even some of the standard modules aren't thread-safe.
 If you're using a module that's not thread-safe for some reason, you can protect yourself by using semaphores and lots of programming discipline to control access to the module.  Semaphores are covered later in the article.  Perl Threads Are Different
  
 Thread Basics
 The core Thread module provides the basic functions you need to write threaded programs.  In the following sections we'll cover the basics, showing you what you need to do to create a threaded program.   After that, we'll go over some of the features of the Thread module that make threaded programming easier.
  
Basic Thread Support
 Thread support is a Perl compile-time option-it's something that's turned on or off when Perl is built at your site, rather than when your programs are compiled. If your Perl wasn't compiled with thread support enabled, then any attempt to use threads will fail.
 Remember that the threading support in 5.005 is in beta release, and should be treated as such.   You should expect that it may not function entirely properly, and the thread interface may well change some before it is a fully supported, production release.  The beta version shouldn't be used for mission-critical projects.  Having said that, threaded Perl is pretty nifty, and worth a look.
 Your programs can use the Config module to check whether threads are enabled. If your program can't run without them, you can say something like:
   $Config{usethreads} or die "Recompile Perl with threads to run this program.";
 A possibly-threaded program using a possibly-threaded module might have code like this:
     use Config;
   use MyMod;
     if ($Config{usethreads}) {
       # We have threads
       require MyMod_threaded;
       import MyMod_threaded;
   } else {
       require MyMod_unthreaded;
       import MyMod_unthreaded;
   }
 Since code that runs both with and without threads is usually pretty messy, it's best to isolate the thread-specific code in its own module.  In our example above, that's what MyMod_threaded is, and it's only imported if we're running on a threaded Perl.
  
Creating Threads
 The Thread package provides the tools you need to create new threads.  Like any other module, you need to tell Perl you want to use it; use Thread imports all the pieces you need to create basic threads.
 The simplest, straightforward way to create a thread is with new():
     use Thread;
     $thr = new Thread \&sub1;
     sub sub1 {
       print "In the thread\n";
   }
 The new() method takes a reference to a subroutine and creates a new thread, which starts executing in the referenced subroutine.  Control then passes both to the subroutine and the caller.
 If you need to, your program can pass parameters to the subroutine as part of the thread startup.  Just include the list of parameters as part of the Thread::new call, like this:
     use Thread;
   $Param3 = "foo";
   $thr = new Thread \&sub1, "Param 1", "Param 2", $Param3;
   $thr = new Thread \&sub1, @ParamList;
   $thr = new Thread \&sub1, qw(Param1 Param2 $Param3);
     sub sub1 {
       my @InboundParameters = @_;
       print "In the thread\n";
       print "got parameters >", join("<>", @InboundParameters), "<\n";
   }
 The subroutine runs like a normal Perl subroutine, and the call to new Thread returns whatever the subroutine returns.
 The last example illustrates another feature of threads.  You can spawn off several threads using the same subroutine.  Each thread executes the same subroutine, but in a separate thread with a separate environment and potentially separate arguments.
 The other way to spawn a new thread is with async(), which is a way to spin off a chunk of code like eval(), but into its own thread:
     use Thread qw(async);
     $LineCount = 0;
     $thr = async {
       while(<>) {$LineCount++}        
       print "Got $LineCount lines\n";
   };
     print "Waiting for the linecount to end\n";
   $thr->join;
   print "All done\n";
 You'll notice we did a use Thread qw(async) in that example.  async is not exported by default, so if you want it, you'll either need to import it before you use it or fully qualify it as Thread::async.  You'll also note that there's a semicolon after the closing brace.  That's because async() treats the following block as an anonymous subroutine, so the semicolon is necessary.
 Like eval(), the code executes in the same context as it would if it weren't spun off.  Since both the code inside and after the async start executing, you need to be careful with any shared resources.  Locking and other synchronization techniques are covered later.
  
Giving up control
 There are times when you may find it useful to have a thread explicitly give up the CPU to another thread.  Your threading package might not support preemptive multitasking for threads, for example, or you may be doing something compute-intensive and want to make sure that the user-interface thread gets called frequently.  Regardless, there are times that you might want a thread to give up the processor.
 Perl's threading package provides the yield() function that does this. yield() is pretty straightforward, and works like this:
     use Thread qw(yield async);
   async {
       my $foo = 50;
       while ($foo--) { print "first async\n" }
       yield;
       $foo = 50;
       while ($foo--) { print "first async\n" }
   };
   async {
       my $foo = 50;
       while ($foo--) { print "second async\n" }
       yield;
       $foo = 50;
       while ($foo--) { print "second async\n" }
   };
  
Waiting For A Thread To Exit
 Since threads are also subroutines, they can return values.  To wait for a thread to exit and extract any scalars it might return, you can use the join() method.
     use Thread;
   $thr = new Thread \&sub1;
     @ReturnData = $thr->join;
   print "Thread returned @ReturnData";
     sub sub1 { return "Fifty-six", "foo", 2; }
 In the example above, the join() method returns as soon as the thread ends.  In addition to waiting for a thread to finish and gathering up any values that the thread might have returned, join() also performs any OS cleanup necessary for the thread.  That cleanup might be important, especially for long-running programs that spawn lots of threads.  If you don't want the return values and don't want to wait for the thread to finish, you should call the detach() method instead. detach() is covered later in the article.
  
Errors In Threads
 So what happens when an error occurs in a thread? Any errors that could be caught with eval() are postponed until the thread is joined.  If your program never joins, the errors appear when your program exits.
 Errors deferred until a join() can be caught with eval():
     use Thread qw(async);
   $thr = async {$b = 3/0};   # Divide by zero error
   $foo = eval {$thr->join};
   if ($@) {
       print "died with error $@\n";
   } else {
       print "Hey, why aren't you dead?\n";
   }
 eval() passes any results from the joined thread back unmodified, so if you want the return value of the thread, this is your only chance to get them.
  
Ignoring A Thread
 join() does three things: it waits for a thread to exit, cleans up after it, and returns any data the thread may have produced.  But what if you're not interested in the thread's return values, and you don't really care when the thread finishes? All you want is for the thread to get cleaned up after when it's done.
 In this case, you use the detach() method.  Once a thread is detached, it'll run until it's finished, then Perl will clean up after it automatically.
     use Thread;
   $thr = new Thread \&sub1; # Spawn the thread
     $thr->detach; # Now we officially don't care any more
     sub sub1 {
       $a = 0;
       while (1) {
           $a++;
           print "\$a is $a\n";
           sleep 1;
       }
   }
 Once a thread is detached, it may not be joined, and any output that it might have produced (if it was done and waiting for a join) is lost.
  
 Threads And Data
 Now that we've covered the basics of threads, it's time for our next topic: data.  Threading introduces a couple of complications to data access that non-threaded programs never need to worry about.
  
Shared And Unshared Data
 The single most important thing to remember when using threads is that all threads potentially have access to all the data anywhere in your program.  While this is true with a nonthreaded Perl program as well, it's especially important to remember with a threaded program, since more than one thread can be accessing this data at once.
 Perl's scoping rules don't change because you're using threads.  If a subroutine (or block, in the case of async()) could see a variable if you weren't running with threads, it can see it if you are.  This is especially important for the subroutines that create, and makes my variables even more important.  Remember--if your variables aren't lexically scoped (declared with my) you're probably sharing them between threads.
  
Thread Pitfall: Races
 While threads bring a new set of useful tools, they also bring a number of pitfalls.  One pitfall is the race condition:
     use Thread;
   $a = 1;
   $thr1 = Thread->new(\&sub1);
   $thr2 = Thread->new(\&sub2);
     sleep 10;
   print "$a\n";
     sub sub1 { $foo = $a; $a = $foo + 1; }
   sub sub2 { $bar = $a; $a = $bar + 1; }
 What do you think $a will be? The answer, unfortunately, is ``it depends.'' Both sub1() and sub2() access the global variable $a, once to read and once to write.  Depending on factors ranging from your thread implementation's scheduling algorithm to the phase of the moon, $a can be 2 or 3.
 Race conditions are caused by unsynchronized access to shared data.  Without explicit synchronization, there's no way to be sure that nothing has happened to the shared data between the time you access it and the time you update it.  Even this simple code fragment has the possibility of error:
     use Thread qw(async);
   $a = 2;
   async{ $b = $a; $a = $b + 1; };
   async{ $c = $a; $a = $c + 1; };
 Two threads both access $a.  Each thread can potentially be interrupted at any point, or be executed in any order.  At the end, $a could be 3 or 4, and both $b and $c could be 2 or 3.
 Whenever your program accesses data or resources that can be accessed by other threads, you must take steps to coordinate access or risk data corruption and race conditions.
  
Controlling access: lock()
 The lock() function takes a variable (or subroutine, but we'll get to that later) and puts a lock on it.  No other thread may lock the variable until the locking thread exits the innermost block containing the lock.  Using lock() is straightforward:
     use Thread qw(async);
   $a = 4;
   $thr1 = async {
       $foo = 12;
       {
           lock ($a); # Block until we get access to $a
           $b = $a;
           $a = $b * $foo;
       }
       print "\$foo was $foo\n";
   };
   $thr2 = async {
       $bar = 7;
       {
           lock ($a); # Block until we can get access to $a
           $c = $a;
           $a = $c * $bar;
       }
       print "\$bar was $bar\n";
   };
   $thr1->join;
   $thr2->join;
   print "\$a is $a\n";
 lock() blocks the thread until the variable being locked is available.  When lock() returns, your thread can be sure that no other thread can lock that variable until the innermost block containing the lock exits.
 It's important to note that locks don't prevent access to the variable in question, only lock attempts.  This is in keeping with Perl's longstanding tradition of courteous programming, and the advisory file locking that flock() gives you.  Locked subroutines behave differently, however.  We'll cover that later in the article.
 You may lock arrays and hashes as well as scalars.  Locking an array, though, will not block subsequent locks on array elements, just lock attempts on the array itself.
 Finally, locks are recursive, which means it's okay for a thread to lock a variable more than once.  The lock will last until the outermost lock() on the variable goes out of scope.
  
Thread Pitfall: Deadlocks
 Locks are a handy tool to synchronize access to data.  Using them properly is the key to safe shared data.  Unfortunately, locks aren't without their dangers.  Consider the following code:
     use Thread qw(async yield);
   $a = 4;
   $b = "foo";
   async {
       lock($a);
       yield;
       sleep 20;
       lock ($b);
   };
   async {
       lock($b);
       yield;
       sleep 20;
       lock ($a);
   };
 This program will probably hang until you kill it.  The only way it won't hang is if one of the two async() routines acquires both locks first.  A guaranteed-to-hang version is more complicated, but the principle is the same.
 The first thread spawned by async() will grab a lock on $a then, a second or two later, try to grab a lock on $b.  Meanwhile, the second thread grabs a lock on $b, then later tries to grab a lock on $a.  The second lock attempt for both threads will block, each waiting for the other to release its lock.
 This condition is called a deadlock, and it occurs whenever two or more threads are trying to get locks on resources that the others own.  Each thread will block, waiting for the other to release a lock on a resource.  That never happens, though, since the thread with the resource is itself waiting for a lock to be released.
 There are a number of ways to handle this sort of problem.  The best way is to always have all threads acquire locks in the exact same order.  If, for example, you lock variables $a, $b, and $c, always lock $a before $b, and $b before $c.  It's also best to hold on to locks for as short a period of time to minimize the risks of deadlock.
  
Queues: Passing Data Around
 A queue is a special thread-safe object that lets you put data in one end and take it out the other without having to worry about synchronization issues.  They're pretty straightforward, and look like this:
     use Thread qw(async);
   use Thread::Queue;
     my $DataQueue = new Thread::Queue;
   $thr = async {
       while ($DataElement = $DataQueue->dequeue) {
           print "Popped $DataElement off the queue\n";
       }
   };
     $DataQueue->enqueue(12);
   $DataQueue->enqueue("A", "B", "C");
   $DataQueue->enqueue(\$thr);
   sleep 10;
   $DataQueue->enqueue(undef);
 You create the queue with new Thread::Queue.  Then you can add lists of scalars onto the end with enqueue(), and pop scalars off the front of it with dequeue().  A queue has no fixed size, and can grow as needed to hold everything pushed on to it.
 If a queue is empty, dequeue() blocks until another thread enqueues something.  This makes queues ideal for event loops and other communications between threads.
  
 Threads And Code
 In addition to providing thread-safe access to data via locks and queues, threaded Perl also provides general-purpose semaphores for coarser synchronization than locks provide and thread-safe access to entire subroutines.
  
Semaphores: Synchronizing Data Access
 Semaphores are a kind of generic locking mechanism.  Unlike lock, which gets a lock on a particular scalar, Perl doesn't associate any particular thing with a semaphore so you can use them to control access to anything you like.  In addition, semaphores can allow more than one thread to access a resource at once, though by default semaphores only allow one thread access at a time.
 Basic semaphores
 Semaphores have two methods, down and up. down decrements the resource count, while up increments it.  down calls will block if the semaphore's current count would decrement below zero.  This program gives a quick demonstration:     use Thread qw(yield);
   use Thread::Semaphore;
   my $semaphore = new Thread::Semaphore;
   $GlobalVariable = 0;
     $thr1 = new Thread \&sample_sub, 1;
   $thr2 = new Thread \&sample_sub, 2;
   $thr3 = new Thread \&sample_sub, 3;
     sub sample_sub {
       my $SubNumber = shift @_;
       my $TryCount = 10;
       my $LocalCopy;
       sleep 1;
       while ($TryCount--) {
           $semaphore->down;
           $LocalCopy = $GlobalVariable;
           print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n";
           yield;
           sleep 2;
           $LocalCopy++;
           $GlobalVariable = $LocalCopy;
           $semaphore->up;
       }
   }
 The three invocations of the subroutine all operate in sync.  The semaphore, though, makes sure that only one thread is accessing the global variable at once.
  
Advanced Semaphores
 By default, semaphores behave like locks, letting only one thread down() them at a time.  However, there are other uses for semaphores. Each semaphore has a counter attached to it. down() decrements the counter and up() increments the counter.  By default, semaphores are created with the counter set to one, down() decrements by one, and up() increments by one.  If down() attempts to decrement the counter below zero, it blocks until the counter is large enough.  Note that while a semaphore can be created with a starting count of zero, any up() or down() always changes the counter by at least one. $semaphore->down(0) is the same as $semaphore->down(1).
 The question, of course, is why would you do something like this? Why create a semaphore with a starting count that's not one, or why decrement/increment it by more than one? The answer is resource availability.  Many resources that you want to manage access for can be safely used by more than one thread at once.
 For example, let's take a GUI driven program.  It has a semaphore that it uses to synchronize access to the display, so only one thread is ever drawing at once.  Handy, but of course you don't want any thread to start drawing until things are properly set up.  In this case, you can create a semaphore with a counter set to zero, and up it when things are ready for drawing.
 Semaphores with counters greater than one are also useful for establishing quotas.  Say, for example, that you have a number of threads that can do I/O at once.  You don't want all the threads reading or writing at once though, since that can potentially swamp your I/O channels, or deplete your process' quota of filehandles.  You can use a semaphore initialized to the number of concurrent I/O requests (or open files) that you want at any one time, and have your threads quietly block and unblock themselves.
 Larger increments or decrements are handy in those cases where a thread needs to check out or return a number of resources at once.
 
  
Attributes: Restricting Access To Subroutines
 In addition to synchronizing access to data or resources, you might find it useful to synchronize access to subroutines.  You may be accessing a singular machine resource (perhaps a vector processor), or find it easier to serialize calls to a particular subroutine than to have a set of locks and sempahores.
 One of the additions to Perl 5.005 is subroutine attributes.  The Thread package uses these to provide several flavors of serialization.  It's important to remember that these attributes are used in the compilation phase of your program so you can't change a subroutine's behavior while your program is actually running.
  
Subroutine Locks
 The basic subroutine lock looks like this:
     sub test_sub :locked {
   }
 This ensures that only one thread will be executing this subroutine at any one time.  Once a thread calls this subroutine, any other thread that calls it will block until the thread in the subroutine exits it.  A more elaborate example looks like this:
     use Thread qw(yield);
     new Thread \&thread_sub, 1;
   new Thread \&thread_sub, 2;
   new Thread \&thread_sub, 3;
   new Thread \&thread_sub, 4;
     sub sync_sub :locked {
       my $CallingThread = shift @_;
       print "In sync_sub for thread $CallingThread\n";
       yield;
       sleep 3;
       print "Leaving sync_sub for thread $CallingThread\n";
   }
     sub thread_sub {
       my $ThreadID = shift @_;
       print "Thread $ThreadID calling sync_sub\n";
       sync_sub($ThreadID);
       print "$ThreadID is done with sync_sub\n";
   }
 The locked attribute tells perl to lock sync_sub(), and if you run this, you can see that only one thread is in it at any one time.
  
Methods
 Locking an entire subroutine can sometimes be overkill, especially when dealing with Perl objects.  When calling a method for an object, for example, you want to serialize calls to a method, so that only one thread will be in the subroutine for a particular object, but threads calling that subroutine for a different object aren't blocked.  The method attribute indicates whether the subroutine is really a method.
     use Thread;
     sub tester {
       my $thrnum = shift @_;
       my $bar = new Foo;
       foreach (1..10) {      
           print "$thrnum calling per_object\n";
           $bar->per_object($thrnum); 
           print "$thrnum out of per_object\n";
           yield;
           print "$thrnum calling one_at_a_time\n";
           $bar->one_at_a_time($thrnum);      
           print "$thrnum out of one_at_a_time\n";
           yield;
       }
   }
     foreach my $thrnum (1..10) {
       new Thread \&tester, $thrnum;
   }
     package Foo;
   sub new {
       my $class = shift @_;
       return bless [@_], $class;
   }
     sub per_object :locked :method {
       my ($class, $thrnum) = @_;
       print "In per_object for thread $thrnum\n";
       yield;
       sleep 2;
       print "Exiting per_object for thread $thrnum\n";
   }
     sub one_at_a_time :locked {
       my ($class, $thrnum) = @_;
       print "In one_at_a_time for thread $thrnum\n";    
       yield;
       sleep 2;
       print "Exiting one_at_a_time for thread $thrnum\n";
   }
 As you can see from the output (omitted for brevity; it's 800 lines) all the threads can be in per_object() simultaneously, but only one thread is ever in one_at_a_time() at once.
  
Locking A Subroutine
 You can lock a subroutine as you would lock a variable.  Subroutine locks work the same as specifying a locked attribute for the subroutine, and block all access to the subroutine for other threads until the lock goes out of scope.  When the subroutine isn't locked, any number of threads can be in it at once, and getting a lock on a subroutine doesn't affect threads already in the subroutine.  Getting a lock on a subroutine looks like this:
     lock(\&sub_to_lock);
 Simple enough.  Unlike the locked attribute, which is a compile time option, locking and unlocking a subroutine can be done at runtime at your discretion.  There is some runtime penalty to using lock(\&sub) instead of the locked attribute, so make sure you're choosing the proper method to do the locking.
 You'd choose lock(\&sub) when writing modules and code to run on both threaded and unthreaded Perl, especially for code that will run on 5.004 or earlier Perls.  In that case, it's useful to have subroutines that should be serialized lock themselves if they're running threaded, like so:
     package Foo;
   use Config;
   $Running_Threaded = 0;
     BEGIN { $Running_Threaded = $Config{'usethreads'} }
     sub sub1 { lock(\&sub1) if $Running_Threaded }
 This way you can ensure single-threadedness regardless of which version of Perl you're running.
  
 General Thread Utility Routines
 We've covered the workhorse parts of Perl's threading package, and with these tools you should be well on your way to writing threaded code and packages.  There are a few useful little pieces that didn't really fit in anyplace else.
  
What Thread Am I In?
 The Thread->self method provides your program with a way to get an object representing the thread it's currently in.  You can use this object in the same way as the ones returned from the thread creation.
  
Thread IDs
 tid() is a thread object method that returns the thread ID of the thread the object represents.  Thread IDs are integers, with the main thread in a program being 0.  Currently Perl assigns a unique tid to every thread ever created in your program, assigning the first thread to be created a tid of 1, and increasing the tid by 1 for each new thread that's created.
  
Are These Threads The Same?
 The equal() method takes two thread objects and returns true  if the objects represent the same thread, and false if they don't.
  
What Threads Are Running?
 Thread->list returns a list of thread objects, one for each thread that's currently running.  Handy for a number of things, including cleaning up at the end of your program:
     # Loop through all the threads
   foreach $thr (Thread->list) {
       # Don't join the main thread or ourselves
       if ($thr->tid && !Thread::equal($thr, Thread->self)) {
           $thr->join;
       }
   }
 The example above is just for illustration.  It isn't strictly necessary to join all the threads you create, since Perl detaches all the threads before it exits.
  
 A Complete Example
 Confused yet? It's time for an example program to show some of the things we've covered.  This program finds prime numbers using threads.
     1  #!/usr/bin/perl -w
   2  # prime-pthread, courtesy of Tom Christiansen
   3
   4  use strict;
   5
   6  use Thread;
   7  use Thread::Queue;
   8
   9  my $stream = new Thread::Queue;
   10 my $kid    = new Thread(\&check_num, $stream, 2);
   11
   12 for my $i ( 3 .. 1000 ) {
   13     $stream->enqueue($i);
   14 }
   15
   16 $stream->enqueue(undef);
   17 $kid->join();
   18
   19 sub check_num {
   20     my ($upstream, $cur_prime) = @_;
   21     my $kid;
   22     my $downstream = new Thread::Queue;
   23     while (my $num = $upstream->dequeue) {
   24         next unless $num % $cur_prime;
   25         if ($kid) {
   26            $downstream->enqueue($num);
   27                  } else {
   28            print "Found prime $num\n";
   29                $kid = new Thread(\&check_num, $downstream, $num);
   30         }
   31     }
   32     $downstream->enqueue(undef) if $kid;
   33     $kid->join()         if $kid;
   34 }
 This program uses the pipeline model to generate prime numbers.  Each thread in the pipeline has an input queue that feeds numbers to be checked, a prime number that it's responsible for, and an output queue that it funnels numbers that have failed the check into.  If the thread has a number that's failed its check and there's no child thread, then the thread must have found a new prime number.  In that case, a new child thread is created for that prime and stuck on the end of the pipeline.
 This probably sounds a bit more confusing than it really is, so lets go through this program piece by piece and see what it does.  (For those of you who might be trying to remember exactly what a prime number is, it's a number that's only evenly divisible by itself and 1)
 The bulk of the work is done by the check_num() subroutine, which takes a reference to its input queue and a prime number that it's responsible for.  After pulling in the input queue and the prime that the subroutine's checking (line 20), we create a new queue (line 22) and reserve a scalar for the thread that we're likely to create later (line 21).
 The while loop from lines 23 to line 31 grabs a scalar off the input queue and checks against the prime this thread is responsible for.  Line 24 checks to see if there's a remainder when we modulo the number to be checked against our prime.  If there is one, the number must not be evenly divisible by our prime, so we need to either pass it on to the next thread if we've created one (line 26) or create a new thread if we haven't.
 The new thread creation is line 29.  We pass on to it a reference to the queue we've created, and the prime number we've found.
 Finally, once the loop terminates (because we got a 0 or undef in the queue, which serves as a note to die), we pass on the notice to our child and wait for it to exit if we've created a child (Lines 32 and 37).
 Meanwhile, back in the main thread, we create a queue (line 9) and the initial child thread (line 10), and pre-seed it with the first prime: 2.  Then we queue all the numbers from 3 to 1000 for checking (lines 12-14), then queue a die notice (line 16) and wait for the first child thread to terminate (line 17).  Because a child won't die until its child has died, we know that we're done once we return from the join.
 That's how it works.  It's pretty simple; as with many Perl programs, the explanation is much longer than the program.
  
 Conclusion
 A complete thread tutorial could fill a book (and has, many times), but this should get you well on your way.  The final authority on how Perl's threads behave is the documention bundled with the Perl distribution, but with what we've covered in this article, you should be well on your way to becoming a threaded Perl expert.
  
 Bibliography
 Here's a short bibliography courtesy of Jürgen Christoffel:
  
Introductory Texts
 Birrell, Andrew D. An Introduction to Programming with Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report #35 online as http://www.research.digital.com/SRC/staff/birrell/bib.html (highly recommended)
 Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A Guide to Concurrency, Communication, and Multithreading. Prentice-Hall, 1996.
 Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written introduction to threads).
 Nelson, Greg (editor). Systems Programming with Modula-3.  Prentice Hall, 1991, ISBN 0-13-590464-1.
 Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell. Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1 (covers POSIX threads).
  
OS-Related References
 Boykin, Joseph, David Kirschen, Alan Langerman, and Susan LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1.
 Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, 1995, ISBN 0-13-143934-0 (great textbook).
 Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4
  
Other References
 Arnold, Ken and James Gosling. The Java Programming Language, 2nd ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.
 Le Sergent, T. and B. Berthomieu. ``Incremental MultiThreaded Garbage Collection on Virtually Shared Memory Architectures'' in Memory Management: Proc. of the International Workshop IWMM 92, St. Malo, France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer, 1992, ISBN 3540-55940-X (real-life thread applications).
  
 Acknowledgements
 Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua Pritikin, and Alan Burlison, for their help in reality-checking and polishing this article.  Big thanks to Tom Christiansen for his rewrite of the prime number generator.
  
 AUTHOR
 Dan Sugalski <sugalskd@ous.edu>
  
 Copyrights
 This article originally appeared in The Perl Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal.  This document may be distributed under the same terms as Perl itself.
   Heshan Wanigasooriya