| 1 | package Lab::Connection; | ||
| 2 | $Lab::Connection::VERSION = '3.899'; | ||
| 3 | #ABSTRACT: Connection base class | ||
| 4 | |||
| 5 | use v5.20; | ||
| 6 | |||
| 7 | use strict; | ||
| 8 | |||
| 9 | #use POSIX; # added for int() function | ||
| 10 | use Lab::Generic; | ||
| 11 | use Time::HiRes qw (usleep sleep); | ||
| 12 | |||
| 13 | use Carp; | ||
| 14 | use Data::Dumper; | ||
| 15 | our $AUTOLOAD; | ||
| 16 | |||
| 17 | our @ISA = ('Lab::Generic'); | ||
| 18 | |||
| 19 | our %fields = ( | ||
| 20 | connection_handle => undef, | ||
| 21 | bus => undef, # set default here in child classes, e.g. bus => "GPIB" | ||
| 22 | bus_class => undef, | ||
| 23 | config => undef, | ||
| 24 | type => undef, # e.g. 'GPIB' | ||
| 25 | ins_debug => 0, # do we need additional output? | ||
| 26 | timeout => 1, # in seconds | ||
| 27 | ); | ||
| 28 | |||
| 29 | sub new { | ||
| 30 | my $proto = shift; | ||
| 31 | my $class = ref($proto) || $proto; | ||
| 32 | my $config = undef; | ||
| 33 | if ( ref $_[0] eq 'HASH' ) { | ||
| 34 | $config = shift; | ||
| 35 | } # try to be flexible about options as hash/hashref | ||
| 36 | else { $config = {@_} } | ||
| 37 | my $self = $class->SUPER::new(@_); | ||
| 38 | bless( $self, $class ); | ||
| 39 | $self->${ \( __PACKAGE__ . '::_construct' ) }(__PACKAGE__); | ||
| 40 | |||
| 41 | $self->config($config); | ||
| 42 | |||
| 43 | return $self; | ||
| 44 | } | ||
| 45 | |||
| 46 | # | ||
| 47 | # generic methods - interface definition | ||
| 48 | # | ||
| 49 | |||
| 50 | sub Clear { | ||
| 51 | my $self = shift; | ||
| 52 | |||
| 53 | # do nothing if connection is blocked | ||
| 54 | if ( $self->{blocked} ) { | ||
| 55 | return undef; | ||
| 56 | } | ||
| 57 | |||
| 58 | return $self->bus()->connection_clear( $self->connection_handle() ) | ||
| 59 | if ( $self->bus()->can('connection_clear') ); | ||
| 60 | |||
| 61 | # error message | ||
| 62 | warn "Clear function is not implemented in the bus " | ||
| 63 | . ref( $self->bus() ) . "\n"; | ||
| 64 | } | ||
| 65 | |||
| 66 | sub Write { | ||
| 67 | my $self = shift; | ||
| 68 | my $options = undef; | ||
| 69 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 70 | else { $options = {@_} } | ||
| 71 | |||
| 72 | # do nothing if connection is blocked | ||
| 73 | if ( $self->{connection_blocked} ) { | ||
| 74 | return undef; | ||
| 75 | } | ||
| 76 | |||
| 77 | return $self->bus() | ||
| 78 | ->connection_write( $self->connection_handle(), $options ); | ||
| 79 | } | ||
| 80 | |||
| 81 | sub Read { | ||
| 82 | my $self = shift; | ||
| 83 | my $options = undef; | ||
| 84 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 85 | else { $options = {@_} } | ||
| 86 | |||
| 87 | # do nothing if connection is blocked | ||
| 88 | if ( $self->{connection_blocked} ) { | ||
| 89 | return undef; | ||
| 90 | } | ||
| 91 | |||
| 92 | my $result = $self->bus() | ||
| 93 | ->connection_read( $self->connection_handle(), $options ); | ||
| 94 | |||
| 95 | # cut off all termination characters: | ||
| 96 | my $temp = $/; | ||
| 97 | if ( ref( $self->config('termchar') ) eq "ARRAY" ) { | ||
| 98 | foreach my $term ( @{ $self->config('termchar') } ) { | ||
| 99 | $/ = $term; | ||
| 100 | chomp($result); | ||
| 101 | } | ||
| 102 | } | ||
| 103 | else { | ||
| 104 | $/ = $self->config('termchar'); | ||
| 105 | chomp($result); | ||
| 106 | } | ||
| 107 | $/ = $temp; | ||
| 108 | |||
| 109 | return $result; | ||
| 110 | } | ||
| 111 | |||
| 112 | sub BrutalRead { | ||
| 113 | my $self = shift; | ||
| 114 | my $options = undef; | ||
| 115 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 116 | else { $options = {@_} } | ||
| 117 | $options->{'brutal'} = 1; | ||
| 118 | |||
| 119 | return $self->Read($options); | ||
| 120 | } | ||
| 121 | |||
| 122 | sub Query { | ||
| 123 | my $self = shift; | ||
| 124 | my $options = undef; | ||
| 125 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 126 | else { $options = {@_} } | ||
| 127 | |||
| 128 | my $wait_query = $options->{'wait_query'} || $self->wait_query(); | ||
| 129 | |||
| 130 | $self->Write($options); | ||
| 131 | sleep($wait_query); | ||
| 132 | return $self->Read($options); | ||
| 133 | } | ||
| 134 | |||
| 135 | sub LongQuery { | ||
| 136 | my $self = shift; | ||
| 137 | my $options = undef; | ||
| 138 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 139 | else { $options = {@_} } | ||
| 140 | |||
| 141 | $options->{read_length} = 10240; | ||
| 142 | return $self->Query($options); | ||
| 143 | } | ||
| 144 | |||
| 145 | sub BrutalQuery { | ||
| 146 | my $self = shift; | ||
| 147 | my $options = undef; | ||
| 148 | if ( ref $_[0] eq 'HASH' ) { $options = shift } | ||
| 149 | else { $options = {@_} } | ||
| 150 | |||
| 151 | $options->{brutal} = 1; | ||
| 152 | return $self->Query($options); | ||
| 153 | } | ||
| 154 | |||
| 155 | sub timeout { | ||
| 156 | my $self = shift; | ||
| 157 | my $timo = shift; | ||
| 158 | |||
| 159 | return $self->{'timeout'} if ( !defined $timo ); | ||
| 160 | |||
| 161 | $self->{'timeout'} = $timo; | ||
| 162 | $self->bus()->timeout( $self->connection_handle(), $timo ) | ||
| 163 | if defined( $self->bus() ) | ||
| 164 | ; # if called by $self->configure() before the bus is created. | ||
| 165 | } | ||
| 166 | |||
| 167 | sub block_connection { | ||
| 168 | my $self = shift; | ||
| 169 | |||
| 170 | $self->{connection_blocked} = 1; | ||
| 171 | |||
| 172 | } | ||
| 173 | |||
| 174 | sub unblock_connection { | ||
| 175 | my $self = shift; | ||
| 176 | |||
| 177 | $self->{connection_blocked} = undef; | ||
| 178 | |||
| 179 | } | ||
| 180 | |||
| 181 | sub is_blocked { | ||
| 182 | my $self = shift; | ||
| 183 | |||
| 184 | if ( $self->{connection_blocked} == 1 ) { | ||
| 185 | return 1; | ||
| 186 | } | ||
| 187 | else { | ||
| 188 | return 0; | ||
| 189 | } | ||
| 190 | |||
| 191 | } | ||
| 192 | |||
| 193 | # | ||
| 194 | # infrastructure stuff below | ||
| 195 | # | ||
| 196 | |||
| 197 | # | ||
| 198 | # Fill $self->device_settings() from config parameters | ||
| 199 | # | ||
| 200 | sub configure { | ||
| 201 | my $self = shift; | ||
| 202 | my $config = shift; | ||
| 203 | |||
| 204 | if ( ref($config) ne 'HASH' ) { | ||
| 205 | Lab::Exception::CorruptParameter->throw( | ||
| 206 | error => 'Given Configuration is not a hash.' ); | ||
| 207 | } | ||
| 208 | else { | ||
| 209 | # | ||
| 210 | # fill matching fields definded in %fields from the configuration hash ($self->config ) | ||
| 211 | # | ||
| 212 | for my $fields_key ( keys %{ $self->{_permitted} } ) { | ||
| 213 | { # restrict scope of "no strict" | ||
| 214 | no strict 'refs'; | ||
| 215 | $self->$fields_key( $config->{$fields_key} ) | ||
| 216 | if exists $config->{$fields_key}; | ||
| 217 | } | ||
| 218 | } | ||
| 219 | } | ||
| 220 | } | ||
| 221 | |||
| 222 | # | ||
| 223 | # Call this in inheriting class's constructors to conveniently initialize the %fields object data | ||
| 224 | # | ||
| 225 | sub _construct { # _construct(__PACKAGE__); | ||
| 226 | ( my $self, my $package ) = ( shift, shift ); | ||
| 227 | my $class = ref($self); | ||
| 228 | my $fields = undef; | ||
| 229 | { | ||
| 230 | no strict 'refs'; | ||
| 231 | $fields = *${ \( $package . '::fields' ) }{HASH}; | ||
| 232 | } | ||
| 233 | |||
| 234 | foreach my $element ( keys %{$fields} ) { | ||
| 235 | $self->{_permitted}->{$element} = $fields->{$element}; | ||
| 236 | } | ||
| 237 | @{$self}{ keys %{$fields} } = values %{$fields}; | ||
| 238 | |||
| 239 | if ( $class eq $package ) { | ||
| 240 | $self->configure( $self->config() ) | ||
| 241 | ; # so that _setbus has access to all the fields | ||
| 242 | $self->_setbus(); | ||
| 243 | $self->configure( $self->config() ) | ||
| 244 | ; # for configuration that needs the bus to be set (timeout()) | ||
| 245 | } | ||
| 246 | } | ||
| 247 | |||
| 248 | # | ||
| 249 | # Method to handle bus creation generically. This is called by _construct(). | ||
| 250 | # If the following (rather simple code) doesn't suit your child class, or your need to | ||
| 251 | # introduce more thorough parameter checking and/or conversion, overwrite it - _construct() | ||
| 252 | # calls it only if it is called by the topmost class in the inheritance hierarchy itself. | ||
| 253 | # | ||
| 254 | # set $self->connection_handle | ||
| 255 | # | ||
| 256 | sub _setbus { # $self->setbus() create new or use existing bus | ||
| 257 | my $self = shift; | ||
| 258 | my $bus_class = $self->bus_class(); | ||
| 259 | |||
| 260 | $self->bus( | ||
| 261 | eval("require $bus_class; new $bus_class(\$self->config());") ) | ||
| 262 | || Lab::Exception::Error->throw( | ||
| 263 | error => "Failed to create bus $bus_class in " | ||
| 264 | . __PACKAGE__ | ||
| 265 | . "::_setbus. Error message was:" | ||
| 266 | . "\n\n----------------------------------------------\n\n" | ||
| 267 | . "$@\n----------------------------------------------\n" ); | ||
| 268 | |||
| 269 | # again, pass it all. | ||
| 270 | $self->connection_handle( | ||
| 271 | $self->bus()->connection_new( $self->config() ) ); | ||
| 272 | } | ||
| 273 | |||
| 274 | sub _configurebus { | ||
| 275 | my $self = shift; | ||
| 276 | |||
| 277 | return; | ||
| 278 | } | ||
| 279 | |||
| 280 | # | ||
| 281 | # config gets it's own accessor - convenient access like $self->config('GPIB_Paddress') instead of $self->config()->{'GPIB_Paddress'} | ||
| 282 | # with a hashref as argument, set $self->{'config'} to the given hashref. | ||
| 283 | # without an argument it returns a reference to $self->config (just like AUTOLOAD would) | ||
| 284 | # | ||
| 285 | sub config { # $value = self->config($key); | ||
| 286 | ( my $self, my $key ) = ( shift, shift ); | ||
| 287 | |||
| 288 | if ( !defined $key ) { | ||
| 289 | return $self->{'config'}; | ||
| 290 | } | ||
| 291 | elsif ( ref($key) =~ /HASH/ ) { | ||
| 292 | return $self->{'config'} = $key; | ||
| 293 | } | ||
| 294 | else { | ||
| 295 | return $self->{'config'}->{$key}; | ||
| 296 | } | ||
| 297 | } | ||
| 298 | |||
| 299 | sub AUTOLOAD { | ||
| 300 | |||
| 301 | my $self = shift; | ||
| 302 | my $type = ref($self) or croak "$self is not an object"; | ||
| 303 | |||
| 304 | my $name = $AUTOLOAD; | ||
| 305 | $name =~ s/.*://; # strip fully qualified portion | ||
| 306 | |||
| 307 | unless ( exists $self->{_permitted}->{$name} ) { | ||
| 308 | Lab::Exception::Error->throw( error => "AUTOLOAD in " | ||
| 309 | . __PACKAGE__ | ||
| 310 | . " couldn't access field '${name}'.\n" ); | ||
| 311 | } | ||
| 312 | |||
| 313 | if (@_) { | ||
| 314 | return $self->{$name} = shift; | ||
| 315 | } | ||
| 316 | else { | ||
| 317 | return $self->{$name}; | ||
| 318 | } | ||
| 319 | } | ||
| 320 | |||
| 321 | # needed so AUTOLOAD doesn't try to call DESTROY on cleanup and prevent the inherited DESTROY | ||
| 322 | sub DESTROY { | ||
| 323 | my $self = shift; | ||
| 324 | $self->SUPER::DESTROY if $self->can("SUPER::DESTROY"); | ||
| 325 | } | ||
| 326 | |||
| 327 | 1; | ||
| 328 | |||
| 329 | |||
| 330 | 1; | ||
| 331 | |||
| 332 | __END__ |