# Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

# All rights reserved.

# This component and the accompanying materials are made available

# under the terms of the License "Eclipse Public License v1.0"

# which accompanies this distribution, and is available

# at the URL "http://www.eclipse.org/legal/epl-v10.html".

# 

# Initial Contributors:

# Nokia Corporation - initial contribution.

# 

# Contributors:

# 

# Description:

# 

#

package CommandController;

use strict;

#

# Constants.

#

use constant READER_SEMAPHORE_NAME => "CommandControllerReaderSemaphore_";

use constant WRITER_SEMAPHORE_NAME => "CommandControllerWriterSemaphore_";

use constant MAX_NUM_CONCURRENT_READERS => 100;

use constant CMD_INDEPENDANT => 0; # Commands that can be run regardless of what else is running.

use constant CMD_ENV_READER => 1;  # Commands that only read the environment.

use constant CMD_ENV_WRITER => 2;  # Commands that modify the environment.

my %commandInfo = (

 		   EnvMembership => CMD_INDEPENDANT,

		   CleanRemote => CMD_INDEPENDANT,

		   ExportEnv => CMD_INDEPENDANT,

		   ExportRel => CMD_INDEPENDANT,

		   CopyRel => CMD_INDEPENDANT,

		   ImportEnv => CMD_INDEPENDANT,

		   ImportRel => CMD_INDEPENDANT,		

		   LatestVer => CMD_INDEPENDANT,

		   PullEnv => CMD_INDEPENDANT,

		   PushEnv => CMD_INDEPENDANT,

		   PushRel => CMD_INDEPENDANT,

		   PullRel => CMD_INDEPENDANT,

		   DeltaEnv => CMD_INDEPENDANT,

		   BinInfo => CMD_ENV_READER,

		   SourceInfo => CMD_ENV_READER,

		   DiffEnv => CMD_ENV_READER,

		   DiffRel => CMD_ENV_READER,

		   ModNotes => CMD_ENV_READER,

		   ViewNotes => CMD_ENV_READER,

		   BuildRel => CMD_ENV_READER,

		   EnvSize => CMD_ENV_READER,

		   MakeSnapShot => CMD_ENV_READER,

		   CleanEnv => CMD_ENV_WRITER,

		   EnvInfo => CMD_ENV_WRITER,

		   GetEnv => CMD_ENV_WRITER,

		   GetRel => CMD_ENV_WRITER,

		   GetSource => CMD_ENV_WRITER,

		   InstallSnapShot => CMD_ENV_WRITER,

		   MakeEnv => CMD_ENV_WRITER,

		   MakeRel => CMD_ENV_WRITER,

		   RemoveRel => CMD_ENV_WRITER,

		   RemoveSource => CMD_ENV_READER,

		   PrepEnv => CMD_ENV_WRITER,

		   PrepRel => CMD_ENV_WRITER,

		   ValidateEnv => CMD_ENV_WRITER,

		   ValidateRel => CMD_ENV_WRITER,

		   EnvData => CMD_ENV_WRITER

		  );

#

# Public.

#

sub New {

  my $pkg = shift;

  my $self = {};

  bless $self, $pkg;

  $self->{iniData} = shift;

  $self->{command} = shift;

  unless ($self->{iniData}->Win32ExtensionsDisabled()) {

    $self->OpenSemaphores();

    unless ($self->CanRun()) {

      die "Error: Cannot run $self->{command} because another command is already running\n";

    }

  }

  return $self;

}

#

# Private.

#

sub CanRun {

  my $self = shift;

  $self->{canRun} = 0;

  my $commandType = $self->CommandType();

  if ($commandType == CMD_INDEPENDANT) {

    $self->{canRun} = 1;

  }

  elsif ($commandType == CMD_ENV_READER) {

    unless ($self->WriterRunning()) {

      $self->{canRun} = 1;

      $self->IncReadersRunning();

    }

  }

  elsif ($commandType == CMD_ENV_WRITER) {

    if (($self->NumReadersRunning() == 0) and not $self->WriterRunning()) {

      $self->{canRun} = 1;

      $self->SetWriterRunning();

    }

  }

  return $self->{canRun};

}

sub DESTROY {

  my $self = shift;

  if ($self->{canRun}) {

    my $commandType = $self->CommandType();

    if ($commandType == CMD_INDEPENDANT) {

      # Nothing to do.

    }

    elsif ($commandType == CMD_ENV_READER) {

      $self->DecReadersRunning();

    }

    elsif ($commandType == CMD_ENV_WRITER) {

      $self->ClearWriterRunning();

    }

  }

}

sub OpenSemaphores {

  my $self = shift;

  my $currentEnvironment = Utils::CurrentDriveLetter() . lc(Utils::EpocRoot());

  $currentEnvironment =~ s/[:\\\/]+/_/g; # Can't have slashes in semaphore name

  require Win32::Semaphore;

  # No longer 'use', as that fails with some versions of Perl

  $self->{writerSemaphore} = Win32::Semaphore->new(0, 2, WRITER_SEMAPHORE_NAME . $currentEnvironment) or die; # 2 because when counting the semaphore, it need to be incremented and then decremented (release(0, $var) doesn't work).

  $self->{readerSemaphore} = Win32::Semaphore->new(0, MAX_NUM_CONCURRENT_READERS, READER_SEMAPHORE_NAME . $currentEnvironment) or die;

}

sub CommandType {

  my $self = shift;

  die unless exists $commandInfo{$self->{command}};

  return $commandInfo{$self->{command}};

}

sub WriterRunning {

  my $self = shift;

  my $writerRunning = SemaphoreCount($self->{writerSemaphore});

  die if $writerRunning > 1;

  return $writerRunning;

}

sub SetWriterRunning {

  my $self = shift;

  SemaphoreInc($self->{writerSemaphore});

}

sub ClearWriterRunning {

  my $self = shift;

  SemaphoreDec($self->{writerSemaphore});

}

sub NumReadersRunning {

  my $self = shift;

  return SemaphoreCount($self->{readerSemaphore});

}

sub IncReadersRunning {

  my $self = shift;

  SemaphoreInc($self->{readerSemaphore});

}

sub DecReadersRunning {

  my $self = shift;

  SemaphoreInc($self->{readerSemaphore});

}

sub SemaphoreCount {

  my $semaphore = shift;

  my $count;

  $semaphore->release(1, $count) or die;

  $semaphore->wait();

  return $count;

}

sub SemaphoreInc {

  my $semaphore = shift;

  $semaphore->release(1) or die;

}

sub SemaphoreDec {

  my $semaphore = shift;

  $semaphore->wait();

}

1;

=head1 NAME

CommandController.pm - Provides a means of controlling which commands can run concurrently within a single environment.

=head1 DESCRIPTION

Certain commands can reliably be run while others are running, whereas others must be run in isolation. This class has responsibility for defining a set of rules regarding concurrent running of commands and ensuring that they are followed. Each command is classified into one of three types:

=over 4

=item 1 Independant

Commands of this type can be run regardless of whatever else may also be running at the time because they neither read nor modify the environment. Commands of this type:

 		   EnvMembership

		   CleanRemote

		   ExportEnv

		   ExportRel

		   ImportEnv

		   ImportRel		

		   LatestVer

		   PullEnv

		   PullRel

		   PushEnv

		   PushRel

		   DeltaEnv

=item 2 Environment readers

Commands of this type can be run provided there aren't any writers running. Commands of this type:

		   BinInfo

		   DiffEnv

		   DiffRel

                   MakeSnapShot

		   ModNotes

                   RemoveSource

		   ViewNotes

=item 3 Environment writers

Commands of this type may modify the state of the environment, and so may only run providing there are no other writers or readers running. Commands of this type:

		   CleanEnv

		   EnvInfo

		   GetEnv

		   GetRel

		   GetSource

                   InstallSnapShot

		   MakeEnv

		   MakeRel

		   RemoveRel

		   PrepEnv

		   PrepRel

		   ValidateEnv

		   ValidateRel

=back

To enforce these runs, multiple instances of C<CommandController> (running in different processes) need to know what else is running at any particular point in time. This information could have been stored in a file, but this has the significant problem that commands that are prematurely killed by the user (perhaps by hitting ctrl-c), they will not cleanup after themselves and so the environment could get stuck in an invalid state. To avoid this problem, a pair of Win32 semaphores are used to count the number of readers and writers currently active at any point in time. Note, only the counting properties of the semaphores are used, which is somewhat unusual (normally semaphores are used to control the execution of threads). The advantage of this scheme is that even if a command is prematurely killed by the user, its handles to the semaphoreswill be released. This may mean that for a period of time the semaphores may have invalid value, but once all commands that are currently running have completed, the semaphores will be destroyed (kernel side) and the environment is guaranteed of being in a 'ready to run' state.

=head1 INTERFACE

=head2 New

Expects to be passed an C<IniData> reference and the name of the command that is about to be run (this is case sensitive). Creates and returns a new C<CommandController> instance if the command if free to run. Dies if not. The C<IniData> reference is used to determine if Win32 extensions have been disabled. If this is the case then the check to see if this command is free to run is not done (since doing so relies on Win32 functionality).

=head1 KNOWN BUGS

None.

=head1 COPYRIGHT

 Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

 All rights reserved.

 This component and the accompanying materials are made available

 under the terms of the License "Eclipse Public License v1.0"

 which accompanies this distribution, and is available

 at the URL "http://www.eclipse.org/legal/epl-v10.html".

 Initial Contributors:

 Nokia Corporation - initial contribution.

 Contributors:

 Description:

=cut