=encoding euc-jp

=head1 NAME

=begin original

Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers

=end original

Time::HiRes - 高精度のalarm, sleep, gettimeofday, インターバル・タイマー

=head1 SYNOPSIS

  use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );

  usleep ($microseconds);

  ualarm ($microseconds);
  ualarm ($microseconds, $interval_microseconds);

  $t0 = [gettimeofday];
  ($seconds, $microseconds) = gettimeofday;

  $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  $elapsed = tv_interval ( $t0, [gettimeofday]);
  $elapsed = tv_interval ( $t0 );

  use Time::HiRes qw ( time alarm sleep );

  $now_fractions = time;
  sleep ($floating_seconds);
  alarm ($floating_seconds);
  alarm ($floating_seconds, $floating_interval);

  use Time::HiRes qw( setitimer getitimer
		      ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );

  setitimer ($which, $floating_seconds, $floating_interval );
  getitimer ($which);

=head1 DESCRIPTION

=begin original

The C<Time::HiRes> module implements a Perl interface to the C<usleep>,
C<ualarm>, C<gettimeofday>, and C<setitimer>/C<getitimer> system calls, in other
words, high resolution time and timers. See the L</EXAMPLES> section below
and the test scripts for usage; see your system documentation for the
description of the underlying C<nanosleep> or C<usleep>, C<ualarm>,
C<gettimeofday>, and C<setitimer>/C<getitimer> calls.

=end original

C<Time::HiRes> モジュールはC<usleep>,C<ualarm>, C<gettimeofday>, そして 
C<setitimer>/C<getitimer> システムコーム、言い換えれば高精度の時刻と
タイマーへのへのPerlインターフェースを実装します。
使い方については下記のL</使用例>セクションとテスト・スクリプトをご覧ください；
基になっているC<nanosleep> あるいは C<usleep>, C<ualarm>, C<gettimeofday>, 
そして C<setitimer>/C<getitimer>については、あなたのシステムのドキュメントを
ご覧ください。

=begin original

If your system lacks C<gettimeofday()> or an emulation of it you don't
get C<gettimeofday()> or the one-argument form of C<tv_interval()>.  If your system lacks all of 
C<nanosleep()>, C<usleep()>, and C<select()>, you don't get
C<Time::HiRes::usleep()> or C<Time::HiRes::sleep()>.  If your system lacks both
C<ualarm()> and C<setitimer()> you don't get
C<Time::HiRes::ualarm()> or C<Time::HiRes::alarm()>.

=end original

あなたのシステムにC<gettimeofday()>やそのエミュレーションがなければ、
C<gettimeofday()>や引数1つの形でのC<tv_interval()>は使えません。
あなたのシステムにC<nanosleep()>, C<usleep()>, そして C<select()>,の全てが
なければ、C<Time::HiRes::usleep()> や C<Time::HiRes::sleep()>は使えません。
あなたのシステムにC<ualarm()> and C<setitimer()> の両方がなければ
C<Time::HiRes::ualarm()> や C<Time::HiRes::alarm()>が使えません。

=begin original

If you try to import an unimplemented function in the C<use> statement
it will fail at compile time.

=end original

C<use>ステートメントのなかで実装されていない関数をインポートしようとすれば、
コンパイル時に失敗します。

=begin original

If your subsecond sleeping is implemented with C<nanosleep()> instead of
C<usleep()>, you can mix subsecond sleeping with signals since
C<nanosleep()> does not use signals.  This, however is unportable, and you
should first check for the truth value of C<&Time::HiRes::d_nanosleep> to
see whether you have nanosleep, and then carefully read your
C<nanosleep()> C API documentation for any peculiarities.  (There is no
separate interface to call C<nanosleep()>; just use C<Time::HiRes::sleep()>
or C<Time::HiRes::usleep()> with small enough values.)

=end original

あなたの１秒以下のsleepがC<usleep()>ではなくC<nanosleep()>で実装されていれば、
C<nanosleep()>はシグナルを使わないので、１秒以下のsleepとシグナルを混在させる
ことができます。しかしこれは移植性を欠きます。そしてまず最初にnanosleepを
持っているのか、C<&Time::HiRes::d_nanosleep>の値がtrueであるかチェック
しなければなりません。それから特有なことがないか慎重にC<nanosleep()> C API
ドキュメントを読まなければなりません。（C<nanosleep()>を呼び出す別の
インターフェースはありません;十分に小さな値で単にC<Time::HiRes::sleep()>や
C<Time::HiRes::usleep()>を呼ぶだけです。)

=begin original

Unless using C<nanosleep> for mixing sleeping with signals, give
some thought to whether Perl is the tool you should be using for work
requiring nanosecond accuracies.

=end original

sleepとシグナルを混在させるためにC<nanosleep>を使わなければ、
Perlがナノ秒の正確さを要求される仕事のために使うべきツールであるか
という疑問があります。

=begin original

The following functions can be imported from this module.
No functions are exported by default.

=end original

このモジュールから以下の関数をインポートすることができます。
デフォルトでエクスポートされる関数はありません。

=over 4

=item gettimeofday ()

=begin original

In array context returns a two-element array with the seconds and
microseconds since the epoch.  In scalar context returns floating
seconds like C<Time::HiRes::time()> (see below).

=end original

配列コンテキストではエポックからの秒とマイクロ秒2つの要素の配列を返します。
スカラー・コンテキストでは、C<Time::HiRes::time()>のように秒を
浮動小数点数で返します（下記参照）。

=item usleep ( $useconds )

=begin original

Sleeps for the number of microseconds specified.  Returns the number
of microseconds actually slept.  Can sleep for more than one second,
unlike the C<usleep> system call. See also C<Time::HiRes::sleep()> below.

=end original

指定されたマイクロ秒数、sleepします。実際にsleepしたマイクロ秒数を
返します。C<usleep>システム・コールとは違い、1秒以上sleepすることができます。
下記のC<Time::HiRes::sleep()>もご覧ください。

=item ualarm ( $useconds [, $interval_useconds ] )

=begin original

Issues a C<ualarm> call; the C<$interval_useconds> is optional and
will be zero if unspecified, resulting in C<alarm>-like behaviour.

=end original

C<ualarm>コールを発行します;C<$interval_useconds>はオプションで、
指定されなければ0になり、その結果はC<alarm>のような動きをします。

=item tv_interval 

tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )

=begin original

Returns the floating seconds between the two times, which should have
been returned by C<gettimeofday()>. If the second argument is omitted,
then the current time is used.

=end original

2つの時刻の時間を浮動小数点の秒数を返します。2つの時刻はC<gettimeofday()>で
返されたものでなければなりません。2番目の引数が省略されると、
現在の時刻が使われます。

=item time ()

=begin original

Returns a floating seconds since the epoch. This function can be
imported, resulting in a nice drop-in replacement for the C<time>
provided with core Perl; see the L</EXAMPLES> below.

=end original

浮動小数点でエポックからの秒数を返します。この関数はインポートする
ことができます、その結果、Perlのコアで提供される差し込み式にC<time>を
置き換えることになります;下記のL</使用例>をご覧ください。

=begin original

B<NOTE 1>: This higher resolution timer can return values either less
or more than the core C<time()>, depending on whether your platform
rounds the higher resolution timer values up, down, or to the nearest second
to get the core C<time()>, but naturally the difference should be never
more than half a second.

=end original

B<注意 1>: この高精度のtimeは、あなたのプラットホームがコアのC<time()>を
得るために、より高精度の時刻を切り上げたり、切り捨てたり、一番近い秒に
するのいずれかによって、コアのC<time()>よりも多かったり、少なかったり
することがあります。しかし当然、その差は0.5秒を越えることはありえません。

=begin original

B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
the C<time()> seconds since epoch rolled over to 1_000_000_000, the
default floating point format of Perl and the seconds since epoch have
conspired to produce an apparent bug: if you print the value of
C<Time::HiRes::time()> you seem to be getting only five decimals, not six
as promised (microseconds).  Not to worry, the microseconds are there
(assuming your platform supports such granularity in first place).
What is going on is that the default floating point format of Perl
only outputs 15 digits.  In this case that means ten digits before the
decimal separator and five after.  To see the microseconds you can use
either C<printf>/C<sprintf> with C<"%.6f">, or the C<gettimeofday()> function in
list context, which will give you the seconds and microseconds as two
separate values.

=end original

B<注意 2>: 2001年9月9日 日曜日 GMTの午前 1:46:40より、
エポックからのC<time()>秒は、1_000_000_000を超えています。
Perlでのデフォルトの浮動小数点のフォーマットとエポックからの秒数が
あいまって明らかなバグを作り出します:C<Time::HiRes::time()>の値を
出力すると、保証された6桁(マイクロ秒)ではなく5桁の数字しか得ることが
できません。ご心配なく。マイクロ秒は存在します(もちろんあなたの
プラットホームが、そのような粒度をサポートしているものと想定しています)。
何が起きているかといえば、Perlの浮動小数点のデフォルトのフォーマットでは
15桁の数字しか出力しません。この場合、小数点の前に0桁の数字があり、
その後ろに5桁あります。マイクロ秒を見るためにはC<"%.6f">でC<printf>/C<sprintf>の
どちらかを使うか、リスト・コンテキストでC<gettimeofday()>を使うことができます。
この場合には、秒とマイクロ秒の2つを別の値として与えてくれます。

=item sleep ( $floating_seconds )

=begin original

Sleeps for the specified amount of seconds.  Returns the number of
seconds actually slept (a floating point value).  This function can be
imported, resulting in a nice drop-in replacement for the C<sleep>
provided with perl, see the L</EXAMPLES> below.

=end original

指定された秒数、sleepします。実際にsleepした秒数を(浮動小数点の値で)
返します。この関数はインポートする
ことができます、その結果、Perlのコアで提供される差し込み式にC<sleep>を
置き換えることになります;下記のL</使用例>をご覧ください。

=item alarm ( $floating_seconds [, $interval_floating_seconds ] )

=begin original

The C<SIGALRM> signal is sent after the specified number of seconds.
Implemented using C<ualarm()>.  The C<$interval_floating_seconds> argument
is optional and will be zero if unspecified, resulting in C<alarm()>-like
behaviour.  This function can be imported, resulting in a nice drop-in
replacement for the C<alarm> provided with perl, see the L</EXAMPLES> below.

=end original

指定され秒数後、C<SIGALRM>シグナルが送られます。C<ualarm()>を使って
実装されています。C<$interval_floating_seconds>引数は
オプションで指定されないと0になります。その結果、C<alarm()>のような
動きになります。この関数はインポートする
ことができます。その結果、Perlのコアで提供される差し込み式にC<alarm>を
置き換えることになります;下記のL</使用例>をご覧ください。

=begin original

B<NOTE 1>: With some operating system and Perl release combinations
C<SIGALRM> restarts C<select()>, instead of interuping it.  
This means that an C<alarm()> followed by a C<select()>
may together take the sum of the times specified for the the
C<alarm()> and the C<select()>, not just the time of the C<alarm()>.

=end original

B<注意 1>: オペレーティング・システムとPerlのリリースの
組み合わせによってはC<SIGALRM>が中断させるのではなく、C<select()>を
再開始させることもあります。これはC<alarm()>の後にC<select()>を
すると、C<alarm()>に指定した時間通りにではなく、
C<alarm()>とC<select()>に指定された時間の合計が掛かるかも
しれないことを意味します。

=item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )

=begin original

Start up an interval timer: after a certain time, a signal arrives,
and more signals may keep arriving at certain intervals.  To disable a
timer, use C<$floating_seconds> of zero.  If the C<$interval_floating_seconds>
is set to zero (or unspecified), the timer is disabled B<after> the
next delivered signal.

=end original

インターバル・タイマーを開始させます;一定の時間後、シグナルが届き、
ある間隔でシグナルが届き続けるかもしれません。タイマーを止めるには、
C<$floating_seconds>を0にしてください。C<$interval_floating_seconds>に
0が指定されると(あるいは指定されないと)、タイマーは次にシグナルが届いた
B<後に>止められます。

=begin original

Use of interval timers may interfere with C<alarm()>, C<sleep()>,
and C<usleep()>.  In standard-speak the "interaction is unspecified",
which means that I<anything> may happen: it may work, it may not.

=end original

インターバル・タイマーを使うことはC<alarm()>, C<sleep()>、C<usleep()>に
よって邪魔されるかもしれません。標準的には「相互作用は特定されていません」
つまりはI<何が>起きるかわかりません:動くかもしれませんし、そうでないかもしれません。

=begin original

In scalar context, the remaining time in the timer is returned.

=end original

スカラー・コンテキストではタイマーでの残り時間が返されます。

=begin original

In list context, both the remaining time and the interval are returned.

=end original

リスト・コンテキストでは、残り時間とインターバルが返されます。

=begin original

There are usually three or four interval timers available: the C<$which>
can be C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, or C<ITIMER_REALPROF>.
Note that which ones are available depends: true UNIX platforms usually
have the first three, but (for example) Win32 and Cygwin have only
C<ITIMER_REAL>, and only Solaris seems to have C<ITIMER_REALPROF> (which is
used to profile multithreaded programs).

=end original

通常3つあるいは4つのインターバル・タイマーが利用可能です:C<$which>は
C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, あるいは C<ITIMER_REALPROF>に
することができます。どれが利用できるかは以下のことに依存します:本当のUNIX
プラットホームは通常最初の3つを持っています。しかし(例えば)Win32とCygwinは
C<ITIMER_REAL>しかもっていません。SolarisはC<ITIMER_REALPROF>を持っているようです
(これはマルチスレッドなプログラムをプロファイルするために使われます)。

=begin original

C<ITIMER_REAL> results in C<alarm()>-like behavior.  Time is counted in
I<real time>; that is, wallclock time.  C<SIGALRM> is delivered when
the timer expires.

=end original

C<ITIMER_REAL>は結果としてC<alarm()>のような動きにします。
時間はI<実時間>;つまり壁時計の時間で計られます。
タイマーが時間切れになるとC<SIGALRM>が送られます。

=begin original

C<ITIMER_VIRTUAL> counts time in (process) I<virtual time>; that is, only
when the process is running.  In multiprocessor/user/CPU systems this
may be more or less than real or wallclock time.  (This time is also
known as the I<user time>.)  C<SIGVTALRM> is delivered when the timer expires.

=end original

C<ITIMER_VIRTUAL>は(プロセス)I<仮想の時間>で時間を計ります；
つまりプロセスが実行しているときだけです。マルチプロセッサ/ユーザ/CPU の
システムではこれは実時間あるいは壁時計の時間とは多かったり、少なかったりします。
(この時間はI<ユーザー時間(user time)>とも呼ばれます。タイマーが
時間切れになるとC<SIGVTALRM>が送られます。

=begin original

C<ITIMER_PROF> counts time when either the process virtual time or when
the operating system is running on behalf of the process (such as I/O).
(This time is also known as the I<system time>.)  (The sum of user
time and system time is known as the I<CPU time>.)  C<SIGPROF> is
delivered when the timer expires.  C<SIGPROF> can interrupt system calls.

=end original

C<ITIMER_PROF> はプロセス仮想時間、あるいは(I/Oのように)プロセスの半分で
オペレーティング・システムが走っている時間を計ります。
(この時間はI<システム時間(system time)>とも呼ばれます。)
タイマーが時間切れになると、C<SIGPROF>が送られます。C<SIGPROF>は
システム・コールを中断させることができます。

=begin original

The semantics of interval timers for multithreaded programs are
system-specific, and some systems may support additional interval
timers.  See your C<setitimer()> documentation.

=end original

マルチスレッドなプログラムでのインターバル・タイマーの意味は
システムによります。そしてシステムによっては、さらに他の
インターバル・タイマーをサポートしているかもしれません。
あなたのC<setitimer()>のドキュメントをご覧ください。

=item getitimer ( $which )

=begin original

Return the remaining time in the interval timer specified by C<$which>.

=end original

C<$which>で指定されたインターバル・タイマーでの残り時間を返します。

=begin original

In scalar context, the remaining time is returned.

=end original

スカラー・コンテキストでは、残り時間が返されます。

=begin original

In list context, both the remaining time and the interval are returned.
The interval is always what you put in using C<setitimer()>.

=end original

リスト・コンテキストでは残り時間とインターバルの両方が返されます。
インターバルは常に、C<setitimer()>を使ったときに入れたものです。

=back

=head1 EXAMPLES

  use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);

  $microseconds = 750_000;
  usleep $microseconds;

=begin original

  # signal alarm in 2.5s & every .1s thereafter
  ualarm 2_500_000, 100_000;	

=end original

  # 2.5秒後、その後は0.1行ごとにシグナル・アラーム
  ualarm 2_500_000, 100_000;    

=begin original

  # get seconds and microseconds since the epoch
  ($s, $usec) = gettimeofday;

=end original

  # エポックからの秒とマイクロ秒を取得
  ($s, $usec) = gettimeofday;

=begin original

  # measure elapsed time 
  # (could also do by subtracting 2 gettimeofday return values)
  $t0 = [gettimeofday];
  # do bunch of stuff here
  $t1 = [gettimeofday];
  # do more stuff here
  $t0_t1 = tv_interval $t0, $t1;

=end original

  # 経過時間の計測
  # (2つのgettimeofdayの戻り値を引くことによっても可能です)
  $t0 = [gettimeofday];
  # ここで何か処理の固まりを実行
  $t1 = [gettimeofday];
  # さらに処理の固まりを実行
  $t0_t1 = tv_interval $t0, $t1;

  $elapsed = tv_interval ($t0, [gettimeofday]);
  $elapsed = tv_interval ($t0);	# equivalent code

=begin original

  #
  # replacements for time, alarm and sleep that know about
  # floating seconds
  #
  use Time::HiRes;
  $now_fractions = Time::HiRes::time;
  Time::HiRes::sleep (2.5);
  Time::HiRes::alarm (10.6666666);

=end original

  #
  # time, alarm そして sleepを浮動小数点での秒がわかる
  # もので置き換え
  #
  use Time::HiRes;
  $now_fractions = Time::HiRes::time;
  Time::HiRes::sleep (2.5);
  Time::HiRes::alarm (10.6666666);

  use Time::HiRes qw ( time alarm sleep );
  $now_fractions = time;
  sleep (2.5);
  alarm (10.6666666);

=begin original

  # Arm an interval timer to go off first at 10 seconds and
  # after that every 2.5 seconds, in process virtual time

=end original

  # プロセス仮想時間で最初に10秒、その後は2.5秒ごとに
  # やってくるインターバルタイマーを装備する

  use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );

  $SIG{VTALRM} = sub { print time, "\n" };
  setitimer(ITIMER_VIRTUAL, 10, 2.5);

=head1 C API

=begin original

In addition to the perl API described above, a C API is available for
extension writers.  The following C functions are available in the
modglobal hash:

=end original

拡張を書く人には上記のperl APIに加えて、C APIを利用することが
利用できます。以下のCの関数がmodglobalハッシュで利用することが
できます:

=begin original

  name             C prototype
  ---------------  ----------------------
  Time::NVtime     double (*)()
  Time::U2time     void (*)(UV ret[2])

=end original

  関数名           Cプロトタイプ
  ---------------  ----------------------
  Time::NVtime     double (*)()
  Time::U2time     void (*)(UV ret[2])

=begin original

Both functions return equivalent information (like C<gettimeofday>)
but with different representations.  The names C<NVtime> and C<U2time>
were selected mainly because they are operating system independent.
(C<gettimeofday> is Unix-centric, though some platforms like VMS have
emulations for it.)

=end original

関数は両方とも(C<gettimeofday>のような)同じ情報を返します。
しかしその表現が違います。C<NVtime> と C<U2time>という名前は主に
オペレーティング・システムに依存していないために選択されています。
(VMSのようにいくつかのプラットホームではそのエミュレーションを
備えていますが、C<gettimeofday>はUnix中心的です。)

=begin original

Here is an example of using C<NVtime> from C:

=end original

CからC<NVtime>を使ったときの例を以下に示します:

  double (*myNVtime)();
  SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
  if (!svp)         croak("Time::HiRes is required");
  if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
  myNVtime = INT2PTR(double(*)(), SvIV(*svp));
  printf("The current time is: %f\n", (*myNVtime)());

=head1 DIAGNOSTICS

=head2 negative time not invented yet

=begin original

You tried to use a negative time argument.

=end original

引数としてマイナスの時刻を使おうとしました。

=head2 internal error: useconds < 0 (unsigned ... signed ...)

=begin original

Something went horribly wrong-- the number of microseconds that cannot
become negative just became negative.  Maybe your compiler is broken?

=end original

何かひどい障害がおきました -- マイナスになるはずのないマイクロ秒数は
マイナスになってしまいました。コンパイラが壊れているのかも？

=head1 CAVEATS

=begin original

Notice that the core C<time()> maybe rounding rather than truncating.
What this means is that the core C<time()> may be reporting the time as one second
later than C<gettimeofday()> and C<Time::HiRes::time()>.

=end original

コアのC<time()>が切り捨てるのではなく、四捨五入するかもしれないことに
注意してください。これはコアのC<time()>がC<gettimeofday()>や
C<Time::HiRes::time()>よりも1秒遅い時間を報告するかもしれないという
ことを意味します。

=head1 AUTHORS

D. Wegscheid <wegscd@whirlpool.com>
R. Schertler <roderick@argon.org>
J. Hietaniemi <jhi@iki.fi>
G. Aas <gisle@aas.no>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 1996-2002 Douglas E. Wegscheid.  All rights reserved.

Copyright (c) 2002,2003,2004 Jarkko Hietaniemi.  All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 翻訳者

川合孝典(GCD00051@nifty.ne.jp)

=cut