-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathunit-parameter.html
More file actions
466 lines (350 loc) · 26.4 KB
/
unit-parameter.html
File metadata and controls
466 lines (350 loc) · 26.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>UNITパラメータクラスの実装 | SOCKET-MANAGER Framework For PHP</title>
<meta name="description" content="SOCKET-MANAGERフレームワークのUNITパラメータクラスの詳細な実装方法を解説。スタックエリアの操作、ユーザー定義エリアの操作、プロトコルUNIT専用メソッドなど、通信データの管理方法を具体的なコード例と共に紹介。" />
<meta content="PHP,ソケット通信,サーバー開発,framework,IPC,ソケットマネージャー" name="keywords">
<link rel="canonical" href="https://socket-manager.github.io/document/unit-parameter.html" />
<script async src="https://www.googletagmanager.com/gtag/js?id=G-LF9W695NNW"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-LF9W695NNW');
</script>
<link rel="icon" href="https://socket-manager.github.io/document/favicon.ico" type="image/x-icon" />
<link type="text/css" rel="stylesheet" href="./css/common.css" media="all" />
<script src="./js/jquery-3.7.1.min.js"></script>
<script type="text/javascript" src="./js/common.js"></script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "SOCKET-MANAGER Framework - UNITパラメータクラスの実装ガイド",
"description": "SOCKET-MANAGERフレームワークにおけるUNITパラメータクラスの実装方法を解説。スタックエリアの操作、ユーザー定義エリアの操作、プロトコルUNIT専用メソッドなど、通信データの管理方法を具体的なコード例と共に紹介。",
"keywords": "PHP, ソケット通信, UNIT, パラメータクラス, ソケットマネージャー",
"articleSection": ["Technical Documentation", "Server Development", "PHP Programming"],
"image": "https://socket-manager.github.io/document/img/architecture/data_stack.png",
"author": {
"@type": "Person",
"name": "SOCKET-MANAGER開発チーム"
},
"publisher": {
"@type": "Organization",
"name": "SOCKET-MANAGER",
"logo": {
"@type": "ImageObject",
"url": "https://socket-manager.github.io/document/logo.png",
"width": 355,
"height": 50
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://socket-manager.github.io/document/unit-parameter.html"
},
"url": "https://socket-manager.github.io/document/unit-parameter.html",
"breadcrumb": {
"@type": "BreadcrumbList",
"itemListElement": [{
"@type": "ListItem",
"position": 1,
"name": "Framework Top",
"item": "https://socket-manager.github.io/document/"
},{
"@type": "ListItem",
"position": 2,
"name": "UNITパラメータクラスの実装",
"item": "https://socket-manager.github.io/document/unit-parameter.html"
}]
},
"isPartOf": {
"@type": "WebSite",
"name": "フレームワークのご紹介",
"url": "https://socket-manager.github.io/document/"
}
}
</script>
</head>
<body>
<div class="layout">
<div class="menu" role="navigation" aria-label="ページメニュー">
<h2 class="menu-title">SOCKET-MANAGER</h2>
<h4 class="menu-reference menu-page-title-bottom"><a href="./reference/" target="_blank">>> Reference</a></h4>
<h2 class="menu-label">MAIN-MENU</h2>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./">▶フレームワークのご紹介</a></h3>
<h3 class="menu-page-title-link"><a href="./event-handler.html">▶イベントハンドラについて</a></h3>
</div>
<h3 class="menu-label-sub">IMPLEMENT</h3>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./init-class.html">▶初期化クラス</a></h3>
<h3 class="menu-page-title">▼UNITパラメータクラス</h3>
<ul>
<li><a href="./unit-parameter.html#begin">はじめに</a></li>
</ul>
<ul>
<li><a href="./unit-parameter.html#image">通信データの管理イメージ</a></li>
</ul>
<ul>
<li><a href="./unit-parameter.html#stack-area">スタックエリアの操作</a></li>
</ul>
<ul>
<li><a href="./unit-parameter.html#user-area">ユーザー定義エリアの操作</a></li>
</ul>
<ul>
<li><a href="./unit-parameter.html#protocol-unit">プロトコルUNIT専用メソッド</a></li>
</ul>
<ul>
<li><a href="./unit-parameter.html#last">おわりに</a></li>
</ul>
<h3 class="menu-page-title-link"><a href="./protocol-unit.html">▶プロトコルUNITクラス</a></h3>
<h3 class="menu-page-title-link"><a href="./command-unit.html">▶コマンドUNITクラス</a></h3>
<h3 class="menu-page-title-link"><a href="./main.html">▶メイン処理クラス</a></h3>
<h3 class="menu-page-title-link"><a href="./setting.html">▶設定ファイル</a></h3>
<h3 class="menu-page-title-link"><a href="./message.html">▶メッセージファイル</a></h3>
</div>
<div class="menu-line"></div>
<div class="menu-text">
<h3 class="menu-page-title-link-for-runtime-manager"><a href="./runtime-manager/" target="_blank">>> ランタイムライブラリ</a></h3>
<h3 class="menu-page-title-link-for-runtime-manager"><a href="./simple-socket/" target="_blank">>> シンプルソケット機能</a></h3>
</div>
<h3 class="menu-label-sub">ADVANCED</h3>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./architecture.html">▶アーキテクチャ</a></h3>
<h3 class="menu-page-title-link"><a href="./event.html">▶イベント駆動アーキテクチャ</a></h3>
<h3 class="menu-page-title-link"><a href="./ipc.html">▶IPC（プロセス間通信）</a></h3>
<h3 class="menu-page-title-link"><a href="./multi-server.html">▶マルチサーバーの構成</a></h3>
<h3 class="menu-page-title-link"><a href="./tcp-and-udp.html">▶TCP/UDP通信について</a></h3>
<h3 class="menu-page-title-link"><a href="./laravel.html">▶Laravelと連携する</a></h3>
<h3 class="menu-page-title-link"><a href="./system-setting.html">▶システム設定ファイル</a></h3>
<h3 class="menu-page-title-link"><a href="./custom-command.html">▶カスタムコマンド作成機能</a></h3>
</div>
<h3 class="menu-label-sub">OTHER-PROJECT</h3>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./new-project.html">▶新規開発環境</a></h3>
<h3 class="menu-page-title-link"><a href="./websocket.html">▶Websocketサーバー開発環境</a></h3>
<h3 class="menu-page-title-link"><a href="./dev-ops.html">▶フレームワークのDevOps環境</a></h3>
</div>
<div class="menu-line"></div>
<div class="menu-text">
<h3 class="menu-page-title-link-for-minecraft"><a href="./minecraft-contents/" target="_blank">>> マインクラフト専用環境</a></h3>
<h3 class="menu-page-title-link-for-launcher"><a href="./launcher/" target="_blank">>> GUI & CLI ランチャー</a></h3>
<h3 class="menu-page-title-link-for-rest-api"><a href="./rest-api/" target="_blank">>> REST-APIサーバー開発環境</a></h3>
</div>
<h2 class="menu-label">EXTRA-MENU</h2>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./extra-demo.html">▶デモサーバーの種類</a></h3>
<h3 class="menu-page-title-link"><a href="./extra-demo-command.html">▶デモのコマンド仕様</a></h3>
<h3 class="menu-page-title-link"><a href="./extra-demo-setting.html">▶デモの設定ファイル</a></h3>
<h3 class="menu-page-title-link"><a href="./extra-minecraft.html">▶マインクラフトの通信仕様</a></h3>
<h3 class="menu-page-title-link"><a href="./extra-close-frame.html">▶切断フレームの検証</a></h3>
</div>
<h2 class="menu-label">PHP-TECHNIQUE</h2>
<div class="menu-text">
<h3 class="menu-page-title-link"><a href="./php-pass-by-reference.html">▶参照渡し</a></h3>
<h3 class="menu-page-title-link"><a href="./php-phpdoc.html">▶PHPDocのフォーマット</a></h3>
</div>
<div class="menu-dummy-for-framework"></div>
</div>
<div class="main" role="main">
<h1>【UNITパラメータクラスの実装】</h1>
<a id="begin"></a>
<h2 class="subtitle">はじめに</h2>
<div class="text-block">
キューとUNITが通信状態のステータス管理を担っているのに対して、このクラスはデータドリブンによるステータス管理の役割を担い、専用のコマンドを使ってスキャフォールディングできます。<br />
UNITの引数として渡されるこのクラスには送受信データスタックを操作するメソッド群が含まれており、UNITを跨ったグローバルコンテキストを制御します。<br /><br />
※キューとUNITの詳細については<font><a href="./event-handler.html" target="_blank">▶イベントハンドラについて</a></font>を参照。<br /><br />
UNIT内では主にこのインスタンスを使って通信処理を実装していく事になりますので、このクラスが制御する通信データの概要と代表的なメソッド群の詳細を以降の項目でご紹介しています。<br /><br />
基底クラスのまま利用する場合は特に新たなクラスを生成する必要はありませんが、例えばチャットサーバーのユーザーリストを管理したり、サーバー間通信で必要になる独自仕様の拡張を行いたいような場合に以下のコマンドを使って生成します。<br />
<pre color-change="command" aria-label="コマンド実行（ParameterForTestというクラス名を指定する場合）">
> php worker craft:parameter ParameterForTest
[success] UNITパラメータクラスの生成に成功しました (ParameterForTest)
</pre><br />
コマンドを実行する事で<code>app/UnitParameter</code>の場所に<code>ParameterForTest</code>というクラス名で<code>SocketManagerParameter</code>クラスを継承したUNITパラメータクラスが生成されます。<br /><br />
</div><br />
<a id="image"></a>
<h2 class="subtitle">通信データの管理イメージ</h2>
<div class="text-block">
このフレームワークでは送受信バッファとして確保しているスタックエリアの制御を行う事で通信データを操作します。<br />
管理イメージは次の通りです。<br />
<div class="img-block">
<a href="./img/architecture/data_stack.png" target="_blank"><img class="img-zoomout" src="./img/architecture/data_stack.png" fetchpriority="high" loading="eager" alt="SOCKET-MANAGER Frameworkの通信データ管理イメージ" /></a>
</div>
上の図の通り、このクラスはディスクリプタ（クライアント接続子）上のデータ制御と深く関わっています。<br />
また、このようなFIFO方式のデータスタックの仕組みを活用する事で、送受信データの取りこぼしを防ぐ事ができ、なおかつ通信データの処理順序も保証する事ができます。<br /><br />
以降ではこのディスクリプタ上の操作を行う代表的なメソッドをご紹介します。<br />
</div><br />
<a id="stack-area"></a>
<h2 class="subtitle">スタックエリアの操作</h2>
<div class="text-block">
ここではディスクリプタ上の送受信スタックエリアを操作するメソッドをご紹介します。<br />
なお、青字の部分は省略できるパラメータを表しています。<br /><br />
<br />
<h3 class="underline">➤受信データの取得</h3>
コマンドディスパッチャーやコマンドUNITで受信データを取得する時に使います。<br />
<pre aria-label="シグネチャ">
【メソッド】getRecvData(): mixed|null
【パラメータ】なし
【戻り値】mixed|null（データなし）
- mixed: アンシリアライザーによって変換された最古の受信データ
- null: 受信データなし
</pre><br />
<br />
<h3 class="underline">➤受信データのスタック</h3>
プロトコルUNITでデータを受信後、コマンドUNITで利用するためにスタックします。<br />
シリアライザーによって変換された受信データがスタック領域にプッシュされます。<br /><br />
※プロトコル部ではシリアライズ化されているデータをそのまま渡す事ができます（内部で自動判別されます）。<br />
※プロセス間通信によって受信したデータをスタックしたい時も使えます。<br />
<pre aria-label="シグネチャ">
【メソッド】setRecvStack($p_data = null, ?bool $p_convert = null, ?string $p_cid = null): void
【パラメータ】
<font class="pre-type">
$p_data - mixed|null - 任意 - スタックするデータ（データタイプは問わない）。デフォルトはnull
$p_convert - bool|null - 任意 - シリアライズ／アンシリアライズの行使フラグ（true：行使する、false：行使しない、デフォルト or null：自動判別）
$p_cid - string|null - 任意 - スタック先のクライアント（接続IDで指定）。デフォルト（null）は自分自身
</font>
【戻り値】なし
</pre>
※第一パラメータはnullを許容するため「任意」となっていますが、基本的には第一パラメータの指定だけで問題ないでしょう。<br /><br />
<br />
<h3 class="underline">➤送信データのスタック</h3>
コマンドUNITでデータを送信する時にスタックします。<br />
シリアライザーによって変換された送信データがスタック領域にプッシュされます。<br /><br />
※スタックされたデータはプロトコルUNITを通してクライアントへ送信されます。<br />
※プロセス間通信で送信するデータをスタックしたい時も使えます。<br />
<pre aria-label="シグネチャ">
【メソッド】setSendStack($p_data = null, ?string $p_cid = null): void
【パラメータ】
<font class="pre-type">
$p_data - mixed|null - 任意 - スタックするデータ（データタイプは問わない）。デフォルトはnull
$p_cid - string|null - 任意 - スタック先のクライアント（接続IDで指定）。デフォルト（null）は自分自身
</font>
【戻り値】なし
</pre>
※第一パラメータはnullを許容するため「任意」となっていますが、基本的には第一パラメータの指定だけで問題ないでしょう。<br /><br />
<br />
<h3 class="subtitle">➤全配信データのスタック</h3>
コマンドUNITで全クライアントへデータを送信する時にスタックします。<br />
シリアライザーによって変換された送信データがスタック領域にプッシュされます。<br /><br />
※スタックされたデータはプロトコルUNITを通してクライアントへ送信されます。<br />
※プロセス間通信で送信するデータをスタックしたい時も使えます。<br />
<pre aria-label="シグネチャ">
【メソッド】setSendStackAll($p_data, bool $p_self_remove = false, $p_fnc = null, $p_param = null): void
【パラメータ】
$p_data - mixed - 必須 - スタックするデータ（データタイプは問わない）
<font class="pre-type">
$p_self_remove - bool - 任意 - 自身のディスクリプタの除外フラグ（true：自身を除外する or false：自身を除外しない）
$p_fnc - mixed|null - 任意 - 処理対象の接続ID評価コールバック
パラメータ:
$p_param - SocketManagerParameter - 任意 - UNITパラメータクラスのインスタンス
SocketManagerParameterクラスのgetConnectionId()メソッドで自身の接続IDを取得する事が可能。
SocketManagerParameterクラスを継承したクラスを指定する事も可能。
戻り値: bool（true：送信対象とする or false：送信対象としない）
SocketManagerParameterクラスの
$p_param - mixed|null - 任意 - コールバックのパラメータ
</font>
【戻り値】なし
</pre>
</div><br />
<a id="user-area"></a>
<h2 class="subtitle">ユーザー定義エリアの操作</h2>
<div class="text-block">
ディスクリプタ上では送受信バッファ以外にもデベロッパーが自由定義できるユーザー定義エリアも確保しています。<br />
ここではそのユーザー定義エリアを操作するメソッドをご紹介します。<br />
なお、青字の部分は省略できるパラメータを表しています。<br /><br />
<br />
<h3 class="underline">➤ユーザー定義エリアのデータ追加／更新</h3>
コマンドディスパッチャーや各UNITで独自のデータを保持したい場合に使います。<br />
指定されたプロパティのキーが存在しなければ追加し、存在していれば上書きします。<br />
<pre aria-label="シグネチャ">
【メソッド】setTempBuff(array $p_prop, ?string $p_cid = null): void
【パラメータ】
$p_prop - array - 必須 - プロパティのリスト（連想配列で指定）
例えばキーと値の関係で['test-data1' => 'テストデータ１', 'test-data2' => 'テストデータ２']のように複数指定可能
<font class="pre-type">
$p_cid - string|null - 任意 - 追加／更新先のクライアント（接続IDで指定）。デフォルト（null）は自分自身
</font>
【戻り値】なし
</pre><br />
<br />
<h3 class="underline">➤ユーザー定義エリアのデータ取得</h3>
コマンドディスパッチャーや各UNITで独自のデータを取得したい場合に使います。<br />
取得対象プロパティのキーのリストを指定して複数取得できます。<br />
一つでも対応するキーが存在しない場合はnullを返します。<br />
<pre aria-label="シグネチャ">
【メソッド】getTempBuff(array $p_prop, ?string $p_cid = null): mixed
【パラメータ】
$p_prop - array - 必須 - プロパティのリスト（連想配列で指定）
例えば['test-data1', 'test-data2']のように複数指定可能。
<font class="pre-type">
$p_cid - string|null - 任意 - 保存先のクライアント（接続IDで指定）。デフォルト（null）は自分自身
</font>
【戻り値】mixed|null
- データが存在する場合: mixed
例えば['test-data1', 'test-data2']と指定した場合、['test-data1' => 'テストデータ１', 'test-data2' => 'テストデータ２']のように返す。
- データが存在しない場合: null
</pre><br />
</div>
<a id="protocol-unit"></a>
<h2 class="subtitle">プロトコルUNIT専用メソッド</h2>
<div class="text-block">
通信データの性質上、必要なデータを一度に送受信できるとは限らないため、ここではポーリング送受信の処理をご紹介しています。<br />
UNITパラメータクラス専用の<code>IProtocolParameter</code>インターフェースを介してメソッドチェーンでアクセスするため<code>$param->protocol()->メソッド名(パラメータ)</code>のように記述します。<br />
なお、このメソッドをコマンドUNITで使おうとすると例外エラー（UnitExceptionEnum::ECODE_METHOD_CALL_FAIL）が発生しますのでご注意ください。<br /><br />
<br />
<h3 class="underline">➤受信サイズの設定</h3>
シリアライズされた通信データをポーリングしながら受信する時の受信サイズを設定します。<br />
データフォーマット上のペイロード長などを指定するために使います。<br />
<pre aria-label="シグネチャ">
【メソッド】setReceivingSize(int $p_size): void
【パラメータ】
$p_size - int - 必須 - 受信サイズ
【戻り値】なし
</pre><br />
<br />
<h3 class="underline">➤データ受信</h3>
シリアライズされた通信データをポーリングしながら受信する時に使用します。<br />
<code>setReceivingSize</code>メソッドで設定されたサイズ分を受信するまでnullを返します。<br />
データ長が設定されたペイロードデータなどを受信するために使います。<br />
<pre aria-label="シグネチャ">
【メソッド】receiving(): mixed
【パラメータ】なし
【戻り値】mixed|null
- 受信データが届いている場合: mixed
- 受信データが届いていない場合: null
</pre><br />
<br />
<h3 class="underline">➤送信データの設定</h3>
シリアライズされた通信データをポーリングしながら送信する時の送信データを設定します。<br />
<pre aria-label="シグネチャ">
【メソッド】setSendingData(string $p_data): void
【パラメータ】
$p_data - string - 必須 - シリアライズされた送信データ
【戻り値】なし
</pre><br />
<br />
<h3 class="underline">➤データ送信</h3>
シリアライズされた通信データをポーリングしながら送信する時に使用します。<br />
設定されたデータを送信完了するまでnullを返します。<br />
<pre aria-label="シグネチャ">
【メソッド】sending(): mixed
【パラメータ】なし
【戻り値】true|null
- 送信完了している場合: true
- 送信中の場合: null
</pre><br />
</div><br />
<a id="last"></a>
<h2 class="subtitle">おわりに</h2>
<div class="text-block">
UNITパラメータクラスはデベロッパーによってインスタンス化され、初期化クラスの<code>getUnitParameter</code>メソッドの戻り値に設定される事で利用可能になり、各UNIT引数を通して渡されます。<br />
つまりフレームワーク内でインスタンス化する事はないので、動的にメモリを圧迫するような心配はなくなります。<br /><br />
ここでご紹介したメソッド群は<code>SocketManagerParameter</code>クラスの一部分です。<font><a href="./reference/index.html" target="_blank">>> Reference</a></font>も合わせてご覧ください。<br />
</div>
</div>
</div>
</body>
</html>