msg_receive
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
msg_receive — メッセージキューからメッセージを受信する
説明
msg_receive
( SysvMessageQueue $queue
, int $desired_message_type
, int &$received_message_type
, int $max_message_size
, mixed &$message
[, bool $unserialize
= true
[, int $flags
= 0
[, int &$error_code
= null
]]] ) : bool
msg_receive() は、指定した queue
から指定した desired_message_type
の最初のメッセージを受信します。
パラメータ
queue
メッセージキュー
desired_message_type
desired_message_type
が 0 の場合、 キューの先頭にあるメッセージが返されます。desiredmsgtype
が 0 より大きな値の場合、その型のメッセージのうち一番最初にあるものが返されます。desired_message_type
が 0 より小さな値の場合、desired_message_type
の絶対値と同じかそれより小さい型のメッセージのうち一番最初にあるものが返されます。 条件を満たすメッセージがない場合は、 条件を満たすメッセージがキューに投入されるまで待ち続けます。 パラメータflags
にMSG_IPC_NOWAIT
を指定することで、 ブロックモードではなくすることが可能です。received_message_type
受信したメッセージの型がこのパラメータに保存されます。
max_message_size
読み込むメッセージの最大サイズは
mmax_message_size
で指定します。もしキューにあるメッセージのサイズがこれより大きい場合、 (以下で説明するflags
が設定されていない限り) この関数は失敗します。message
エラーが発生しなければ、 受信したメッセージは
message
に保存されます。unserialize
このパラメータが
true
に設定されている場合、 メッセージはセッションモジュールと同様の方法でシリアライズされているものとみなされます。 メッセージは元の状態に復元されたうえでスクリプトに返されます。 これにより、配列やオブジェクト構造体のような複雑な形式のデータを他の PHP スクリプトから簡単に受信することが可能となります。 また、もし WDDX シリアライザを使用しているなら、あらゆる WDDX 互換のソースからデータを受け取ることが可能となります。unserialize
がfalse
の場合、 メッセージはバイナリセーフな文字列として返されます。flags
オプションの
flags
により、低レベルの msgrcv システムコールにフラグを渡すことが可能です。デフォルト値は 0 ですが、以下の値のうちのいくつかを(値を足すかあるいは論理和ととることで) 指定することが可能です。msg_receive のフラグの値 MSG_IPC_NOWAIT
desired_message_type
を満たすメッセージが存在しない場合に、待ち続けずにすぐに結果を返します。 関数は失敗し、
MSG_ENOMSG
に対応する整数値を返します。MSG_EXCEPT
このフラグを正の desired_message_type
と組み合わせて使用すると、この関数は
desired_message_type
以外の型をもつ 最初のメッセージを受信するようになります。MSG_NOERROR
このフラグを設定しておくと、メッセージが max_message_size
より大きい場合に そのメッセージをmax_message_size
までに切り詰め、 エラーを返しません。error_code
エラーが発生した場合は、オプションの
error_code
にシステムの errno 値が設定されます。
返り値
成功した場合に true
を、失敗した場合に false
を返します。
処理が正常に完了すると、メッセージキューデータ構造体は以下のように更新されます。
msg_lrpid
には呼び出し元のプロセス ID が
設定され、msg_qnum
が 1 減少し、
msg_rtime
が現在の時刻に設定されます。
変更履歴
バージョン | 説明 |
---|---|
8.0.0 | 引数 queue は、
SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。 |
参考
- msg_remove_queue() - メッセージキューを破棄する
- msg_send() - メッセージキューにメッセージを送信する
- msg_stat_queue() - メッセージキューデータ構造体の情報を返す
- msg_set_queue() - メッセージキューデータ構造体の情報を設定する