1# Manage the POE::Kernel data structures necessary to keep track of
2# session aliases.
3
4package POE::Resource::Aliases;
5
6use vars qw($VERSION);
7$VERSION = '1.368'; # NOTE - Should be #.### (three decimal places)
8
9# These methods are folded into POE::Kernel;
10package POE::Kernel;
11
12use strict;
13
14### The table of session aliases, and the sessions they refer to.
15
16my %kr_aliases;
17#  ( $alias => $session_ref,
18#    ...,
19#  );
20
21my %kr_ses_to_alias;
22#  ( $session_id =>
23#    { $alias => $session_ref,
24#      ...,
25#    },
26#    ...,
27#  );
28
29sub _data_alias_initialize {
30  $poe_kernel->[KR_ALIASES] = \%kr_aliases;
31}
32
33sub _data_alias_relocate_kernel_id {
34  my ($self, $old_id, $new_id) = @_;
35  return unless exists $kr_ses_to_alias{$old_id};
36  $kr_ses_to_alias{$new_id} = delete $kr_ses_to_alias{$old_id};
37}
38
39### End-run leak checking.  Returns true if finalization was ok, or
40### false if it failed.
41
42sub _data_alias_finalize {
43  my $finalized_ok = 1;
44  while (my ($alias, $ses) = each(%kr_aliases)) {
45    _warn "!!! Leaked alias: $alias = $ses\n";
46    $finalized_ok = 0;
47  }
48  while (my ($ses_id, $alias_rec) = each(%kr_ses_to_alias)) {
49    my @aliases = keys(%$alias_rec);
50    _warn "!!! Leaked alias cross-reference: $ses_id (@aliases)\n";
51    $finalized_ok = 0;
52  }
53  return $finalized_ok;
54}
55
56# Add an alias to a session.
57#
58# TODO This has a potential problem: setting the same alias twice on a
59# session will increase the session's reference count twice.  Removing
60# the alias will only decrement it once.  That potentially causes
61# reference counts that never go away.  The public interface for this
62# function, alias_set(), does not allow this to occur.  We should add
63# a test to make sure it never does.
64#
65# TODO It is possible to add aliases to sessions that do not exist.
66# The public alias_set() function prevents this from happening.
67
68sub _data_alias_add {
69  my ($self, $session, $alias) = @_;
70#  _warn( "Session ", $session->ID, " is alias $alias\n" );
71  $self->_data_ses_refcount_inc($session->ID);
72  $kr_aliases{$alias} = $session;
73  $kr_ses_to_alias{$session->ID}->{$alias} = $session;
74}
75
76# Remove an alias from a session.
77#
78# TODO Happily allows the removal of aliases from sessions that don't
79# exist.  This will cause problems with reference counting.
80
81sub _data_alias_remove {
82  my ($self, $session, $alias) = @_;
83#  _warn( "Session ", $session->ID, " was alias $alias\n" );
84  delete $kr_aliases{$alias};
85  delete $kr_ses_to_alias{$session->ID}->{$alias};
86  $self->_data_ses_refcount_dec($session->ID);
87}
88
89### Clear all the aliases from a session.
90
91sub _data_alias_clear_session {
92  my ($self, $sid) = @_;
93  return unless exists $kr_ses_to_alias{$sid}; # avoid autoviv
94  while (my ($alias, $ses_ref) = each %{$kr_ses_to_alias{$sid}}) {
95    $self->_data_alias_remove($ses_ref, $alias);
96  }
97  delete $kr_ses_to_alias{$sid};
98}
99
100### Resolve an alias.  Just an alias.
101
102sub _data_alias_resolve {
103  my ($self, $alias) = @_;
104  return undef unless exists $kr_aliases{$alias};
105  return $kr_aliases{$alias};
106}
107
108### Return a list of aliases for a session.
109
110sub _data_alias_list {
111  my ($self, $sid) = @_;
112  return () unless exists $kr_ses_to_alias{$sid};
113  return sort keys %{$kr_ses_to_alias{$sid}};
114}
115
116### Return the number of aliases for a session.
117
118sub _data_alias_count_ses {
119  my ($self, $sid) = @_;
120  return 0 unless exists $kr_ses_to_alias{$sid};
121  return scalar keys %{$kr_ses_to_alias{$sid}};
122}
123
124### Return a session's ID in a form suitable for logging.
125
126sub _data_alias_loggable {
127  my ($self, $sid) = @_;
128  "session $sid" . (
129    (exists $kr_ses_to_alias{$sid})
130    ? ( " (" . join(", ", $self->_data_alias_list($sid)) . ")" )
131    : ""
132  );
133}
134
1351;
136
137__END__
138
139=head1 NAME
140
141POE::Resource::Aliases - internal session alias manager for POE::Kernel
142
143=head1 SYNOPSIS
144
145There is no public API.
146
147=head1 DESCRIPTION
148
149POE::Resource::Aliases is a mix-in class for POE::Kernel.  It provides
150the features to manage session aliases.  It is used internally by
151POE::Kernel, so it has no public interface.
152
153=head1 SEE ALSO
154
155See L<POE::Kernel/Session Identifiers (IDs and Aliases)> for the
156public alias API.
157
158See L<POE::Kernel/Resources> for public information about POE
159resources.
160
161See L<POE::Resource> for general discussion about resources and the
162classes that manage them.
163
164=head1 BUGS
165
166None known.
167
168=head1 AUTHORS & COPYRIGHTS
169
170Please see L<POE> for more information about authors and contributors.
171
172=cut
173
174# rocco // vim: ts=2 sw=2 expandtab
175# TODO - Edit.
176